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 /* -- interrupt callbacks -- */ 2185 void (*transfer_ack_begin)(struct snd_pcm_substream *substream); 2186 void (*transfer_ack_end)(struct snd_pcm_substream *substream); 2187 2188 /* -- timer -- */ 2189 unsigned int timer_resolution; /* timer resolution */ 2190 2191 /* -- DMA -- */ 2192 unsigned char *dma_area; /* DMA area */ 2193 dma_addr_t dma_addr; /* physical bus address (not accessible from main CPU) */ 2194 size_t dma_bytes; /* size of DMA area */ 2195 2196 struct snd_dma_buffer *dma_buffer_p; /* allocated buffer */ 2197 2198#if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE) 2199 /* -- OSS things -- */ 2200 struct snd_pcm_oss_runtime oss; 2201#endif 2202}; 2203]]> 2204 </programlisting> 2205 </informalexample> 2206 </para> 2207 2208 <para> 2209 For the operators (callbacks) of each sound driver, most of 2210 these records are supposed to be read-only. Only the PCM 2211 middle-layer changes / updates them. The exceptions are 2212 the hardware description (hw), interrupt callbacks 2213 (transfer_ack_xxx), DMA buffer information, and the private 2214 data. Besides, if you use the standard buffer allocation 2215 method via <function>snd_pcm_lib_malloc_pages()</function>, 2216 you don't need to set the DMA buffer information by yourself. 2217 </para> 2218 2219 <para> 2220 In the sections below, important records are explained. 2221 </para> 2222 2223 <section id="pcm-interface-runtime-hw"> 2224 <title>Hardware Description</title> 2225 <para> 2226 The hardware descriptor (struct <structname>snd_pcm_hardware</structname>) 2227 contains the definitions of the fundamental hardware 2228 configuration. Above all, you'll need to define this in 2229 <link linkend="pcm-interface-operators-open-callback"><citetitle> 2230 the open callback</citetitle></link>. 2231 Note that the runtime instance holds the copy of the 2232 descriptor, not the pointer to the existing descriptor. That 2233 is, in the open callback, you can modify the copied descriptor 2234 (<constant>runtime->hw</constant>) as you need. For example, if the maximum 2235 number of channels is 1 only on some chip models, you can 2236 still use the same hardware descriptor and change the 2237 channels_max later: 2238 <informalexample> 2239 <programlisting> 2240<![CDATA[ 2241 struct snd_pcm_runtime *runtime = substream->runtime; 2242 ... 2243 runtime->hw = snd_mychip_playback_hw; /* common definition */ 2244 if (chip->model == VERY_OLD_ONE) 2245 runtime->hw.channels_max = 1; 2246]]> 2247 </programlisting> 2248 </informalexample> 2249 </para> 2250 2251 <para> 2252 Typically, you'll have a hardware descriptor as below: 2253 <informalexample> 2254 <programlisting> 2255<![CDATA[ 2256 static struct snd_pcm_hardware snd_mychip_playback_hw = { 2257 .info = (SNDRV_PCM_INFO_MMAP | 2258 SNDRV_PCM_INFO_INTERLEAVED | 2259 SNDRV_PCM_INFO_BLOCK_TRANSFER | 2260 SNDRV_PCM_INFO_MMAP_VALID), 2261 .formats = SNDRV_PCM_FMTBIT_S16_LE, 2262 .rates = SNDRV_PCM_RATE_8000_48000, 2263 .rate_min = 8000, 2264 .rate_max = 48000, 2265 .channels_min = 2, 2266 .channels_max = 2, 2267 .buffer_bytes_max = 32768, 2268 .period_bytes_min = 4096, 2269 .period_bytes_max = 32768, 2270 .periods_min = 1, 2271 .periods_max = 1024, 2272 }; 2273]]> 2274 </programlisting> 2275 </informalexample> 2276 </para> 2277 2278 <para> 2279 <itemizedlist> 2280 <listitem><para> 2281 The <structfield>info</structfield> field contains the type and 2282 capabilities of this pcm. The bit flags are defined in 2283 <filename><sound/asound.h></filename> as 2284 <constant>SNDRV_PCM_INFO_XXX</constant>. Here, at least, you 2285 have to specify whether the mmap is supported and which 2286 interleaved format is supported. 2287 When the hardware supports mmap, add the 2288 <constant>SNDRV_PCM_INFO_MMAP</constant> flag here. When the 2289 hardware supports the interleaved or the non-interleaved 2290 formats, <constant>SNDRV_PCM_INFO_INTERLEAVED</constant> or 2291 <constant>SNDRV_PCM_INFO_NONINTERLEAVED</constant> flag must 2292 be set, respectively. If both are supported, you can set both, 2293 too. 2294 </para> 2295 2296 <para> 2297 In the above example, <constant>MMAP_VALID</constant> and 2298 <constant>BLOCK_TRANSFER</constant> are specified for the OSS mmap 2299 mode. Usually both are set. Of course, 2300 <constant>MMAP_VALID</constant> is set only if the mmap is 2301 really supported. 2302 </para> 2303 2304 <para> 2305 The other possible flags are 2306 <constant>SNDRV_PCM_INFO_PAUSE</constant> and 2307 <constant>SNDRV_PCM_INFO_RESUME</constant>. The 2308 <constant>PAUSE</constant> bit means that the pcm supports the 2309 <quote>pause</quote> operation, while the 2310 <constant>RESUME</constant> bit means that the pcm supports 2311 the full <quote>suspend/resume</quote> operation. 2312 If the <constant>PAUSE</constant> flag is set, 2313 the <structfield>trigger</structfield> callback below 2314 must handle the corresponding (pause push/release) commands. 2315 The suspend/resume trigger commands can be defined even without 2316 the <constant>RESUME</constant> flag. See <link 2317 linkend="power-management"><citetitle> 2318 Power Management</citetitle></link> section for details. 2319 </para> 2320 2321 <para> 2322 When the PCM substreams can be synchronized (typically, 2323 synchronized start/stop of a playback and a capture streams), 2324 you can give <constant>SNDRV_PCM_INFO_SYNC_START</constant>, 2325 too. In this case, you'll need to check the linked-list of 2326 PCM substreams in the trigger callback. This will be 2327 described in the later section. 2328 </para> 2329 </listitem> 2330 2331 <listitem> 2332 <para> 2333 <structfield>formats</structfield> field contains the bit-flags 2334 of supported formats (<constant>SNDRV_PCM_FMTBIT_XXX</constant>). 2335 If the hardware supports more than one format, give all or'ed 2336 bits. In the example above, the signed 16bit little-endian 2337 format is specified. 2338 </para> 2339 </listitem> 2340 2341 <listitem> 2342 <para> 2343 <structfield>rates</structfield> field contains the bit-flags of 2344 supported rates (<constant>SNDRV_PCM_RATE_XXX</constant>). 2345 When the chip supports continuous rates, pass 2346 <constant>CONTINUOUS</constant> bit additionally. 2347 The pre-defined rate bits are provided only for typical 2348 rates. If your chip supports unconventional rates, you need to add 2349 the <constant>KNOT</constant> bit and set up the hardware 2350 constraint manually (explained later). 2351 </para> 2352 </listitem> 2353 2354 <listitem> 2355 <para> 2356 <structfield>rate_min</structfield> and 2357 <structfield>rate_max</structfield> define the minimum and 2358 maximum sample rate. This should correspond somehow to 2359 <structfield>rates</structfield> bits. 2360 </para> 2361 </listitem> 2362 2363 <listitem> 2364 <para> 2365 <structfield>channel_min</structfield> and 2366 <structfield>channel_max</structfield> 2367 define, as you might already expected, the minimum and maximum 2368 number of channels. 2369 </para> 2370 </listitem> 2371 2372 <listitem> 2373 <para> 2374 <structfield>buffer_bytes_max</structfield> defines the 2375 maximum buffer size in bytes. There is no 2376 <structfield>buffer_bytes_min</structfield> field, since 2377 it can be calculated from the minimum period size and the 2378 minimum number of periods. 2379 Meanwhile, <structfield>period_bytes_min</structfield> and 2380 define the minimum and maximum size of the period in bytes. 2381 <structfield>periods_max</structfield> and 2382 <structfield>periods_min</structfield> define the maximum and 2383 minimum number of periods in the buffer. 2384 </para> 2385 2386 <para> 2387 The <quote>period</quote> is a term that corresponds to 2388 a fragment in the OSS world. The period defines the size at 2389 which a PCM interrupt is generated. This size strongly 2390 depends on the hardware. 2391 Generally, the smaller period size will give you more 2392 interrupts, that is, more controls. 2393 In the case of capture, this size defines the input latency. 2394 On the other hand, the whole buffer size defines the 2395 output latency for the playback direction. 2396 </para> 2397 </listitem> 2398 2399 <listitem> 2400 <para> 2401 There is also a field <structfield>fifo_size</structfield>. 2402 This specifies the size of the hardware FIFO, but currently it 2403 is neither used in the driver nor in the alsa-lib. So, you 2404 can ignore this field. 2405 </para> 2406 </listitem> 2407 </itemizedlist> 2408 </para> 2409 </section> 2410 2411 <section id="pcm-interface-runtime-config"> 2412 <title>PCM Configurations</title> 2413 <para> 2414 Ok, let's go back again to the PCM runtime records. 2415 The most frequently referred records in the runtime instance are 2416 the PCM configurations. 2417 The PCM configurations are stored in the runtime instance 2418 after the application sends <type>hw_params</type> data via 2419 alsa-lib. There are many fields copied from hw_params and 2420 sw_params structs. For example, 2421 <structfield>format</structfield> holds the format type 2422 chosen by the application. This field contains the enum value 2423 <constant>SNDRV_PCM_FORMAT_XXX</constant>. 2424 </para> 2425 2426 <para> 2427 One thing to be noted is that the configured buffer and period 2428 sizes are stored in <quote>frames</quote> in the runtime. 2429 In the ALSA world, 1 frame = channels * samples-size. 2430 For conversion between frames and bytes, you can use the 2431 <function>frames_to_bytes()</function> and 2432 <function>bytes_to_frames()</function> helper functions. 2433 <informalexample> 2434 <programlisting> 2435<![CDATA[ 2436 period_bytes = frames_to_bytes(runtime, runtime->period_size); 2437]]> 2438 </programlisting> 2439 </informalexample> 2440 </para> 2441 2442 <para> 2443 Also, many software parameters (sw_params) are 2444 stored in frames, too. Please check the type of the field. 2445 <type>snd_pcm_uframes_t</type> is for the frames as unsigned 2446 integer while <type>snd_pcm_sframes_t</type> is for the frames 2447 as signed integer. 2448 </para> 2449 </section> 2450 2451 <section id="pcm-interface-runtime-dma"> 2452 <title>DMA Buffer Information</title> 2453 <para> 2454 The DMA buffer is defined by the following four fields, 2455 <structfield>dma_area</structfield>, 2456 <structfield>dma_addr</structfield>, 2457 <structfield>dma_bytes</structfield> and 2458 <structfield>dma_private</structfield>. 2459 The <structfield>dma_area</structfield> holds the buffer 2460 pointer (the logical address). You can call 2461 <function>memcpy</function> from/to 2462 this pointer. Meanwhile, <structfield>dma_addr</structfield> 2463 holds the physical address of the buffer. This field is 2464 specified only when the buffer is a linear buffer. 2465 <structfield>dma_bytes</structfield> holds the size of buffer 2466 in bytes. <structfield>dma_private</structfield> is used for 2467 the ALSA DMA allocator. 2468 </para> 2469 2470 <para> 2471 If you use a standard ALSA function, 2472 <function>snd_pcm_lib_malloc_pages()</function>, for 2473 allocating the buffer, these fields are set by the ALSA middle 2474 layer, and you should <emphasis>not</emphasis> change them by 2475 yourself. You can read them but not write them. 2476 On the other hand, if you want to allocate the buffer by 2477 yourself, you'll need to manage it in hw_params callback. 2478 At least, <structfield>dma_bytes</structfield> is mandatory. 2479 <structfield>dma_area</structfield> is necessary when the 2480 buffer is mmapped. If your driver doesn't support mmap, this 2481 field is not necessary. <structfield>dma_addr</structfield> 2482 is also optional. You can use 2483 <structfield>dma_private</structfield> as you like, too. 2484 </para> 2485 </section> 2486 2487 <section id="pcm-interface-runtime-status"> 2488 <title>Running Status</title> 2489 <para> 2490 The running status can be referred via <constant>runtime->status</constant>. 2491 This is the pointer to the struct <structname>snd_pcm_mmap_status</structname> 2492 record. For example, you can get the current DMA hardware 2493 pointer via <constant>runtime->status->hw_ptr</constant>. 2494 </para> 2495 2496 <para> 2497 The DMA application pointer can be referred via 2498 <constant>runtime->control</constant>, which points to the 2499 struct <structname>snd_pcm_mmap_control</structname> record. 2500 However, accessing directly to this value is not recommended. 2501 </para> 2502 </section> 2503 2504 <section id="pcm-interface-runtime-private"> 2505 <title>Private Data</title> 2506 <para> 2507 You can allocate a record for the substream and store it in 2508 <constant>runtime->private_data</constant>. Usually, this 2509 is done in 2510 <link linkend="pcm-interface-operators-open-callback"><citetitle> 2511 the open callback</citetitle></link>. 2512 Don't mix this with <constant>pcm->private_data</constant>. 2513 The <constant>pcm->private_data</constant> usually points to the 2514 chip instance assigned statically at the creation of PCM, while the 2515 <constant>runtime->private_data</constant> points to a dynamic 2516 data structure created at the PCM open callback. 2517 2518 <informalexample> 2519 <programlisting> 2520<![CDATA[ 2521 static int snd_xxx_open(struct snd_pcm_substream *substream) 2522 { 2523 struct my_pcm_data *data; 2524 .... 2525 data = kmalloc(sizeof(*data), GFP_KERNEL); 2526 substream->runtime->private_data = data; 2527 .... 2528 } 2529]]> 2530 </programlisting> 2531 </informalexample> 2532 </para> 2533 2534 <para> 2535 The allocated object must be released in 2536 <link linkend="pcm-interface-operators-open-callback"><citetitle> 2537 the close callback</citetitle></link>. 2538 </para> 2539 </section> 2540 2541 <section id="pcm-interface-runtime-intr"> 2542 <title>Interrupt Callbacks</title> 2543 <para> 2544 The field <structfield>transfer_ack_begin</structfield> and 2545 <structfield>transfer_ack_end</structfield> are called at 2546 the beginning and at the end of 2547 <function>snd_pcm_period_elapsed()</function>, respectively. 2548 </para> 2549 </section> 2550 2551 </section> 2552 2553 <section id="pcm-interface-operators"> 2554 <title>Operators</title> 2555 <para> 2556 OK, now let me give details about each pcm callback 2557 (<parameter>ops</parameter>). In general, every callback must 2558 return 0 if successful, or a negative error number 2559 such as <constant>-EINVAL</constant>. To choose an appropriate 2560 error number, it is advised to check what value other parts of 2561 the kernel return when the same kind of request fails. 2562 </para> 2563 2564 <para> 2565 The callback function takes at least the argument with 2566 <structname>snd_pcm_substream</structname> pointer. To retrieve 2567 the chip record from the given substream instance, you can use the 2568 following macro. 2569 2570 <informalexample> 2571 <programlisting> 2572<![CDATA[ 2573 int xxx() { 2574 struct mychip *chip = snd_pcm_substream_chip(substream); 2575 .... 2576 } 2577]]> 2578 </programlisting> 2579 </informalexample> 2580 2581 The macro reads <constant>substream->private_data</constant>, 2582 which is a copy of <constant>pcm->private_data</constant>. 2583 You can override the former if you need to assign different data 2584 records per PCM substream. For example, the cmi8330 driver assigns 2585 different private_data for playback and capture directions, 2586 because it uses two different codecs (SB- and AD-compatible) for 2587 different directions. 2588 </para> 2589 2590 <section id="pcm-interface-operators-open-callback"> 2591 <title>open callback</title> 2592 <para> 2593 <informalexample> 2594 <programlisting> 2595<![CDATA[ 2596 static int snd_xxx_open(struct snd_pcm_substream *substream); 2597]]> 2598 </programlisting> 2599 </informalexample> 2600 2601 This is called when a pcm substream is opened. 2602 </para> 2603 2604 <para> 2605 At least, here you have to initialize the runtime->hw 2606 record. Typically, this is done by like this: 2607 2608 <informalexample> 2609 <programlisting> 2610<![CDATA[ 2611 static int snd_xxx_open(struct snd_pcm_substream *substream) 2612 { 2613 struct mychip *chip = snd_pcm_substream_chip(substream); 2614 struct snd_pcm_runtime *runtime = substream->runtime; 2615 2616 runtime->hw = snd_mychip_playback_hw; 2617 return 0; 2618 } 2619]]> 2620 </programlisting> 2621 </informalexample> 2622 2623 where <parameter>snd_mychip_playback_hw</parameter> is the 2624 pre-defined hardware description. 2625 </para> 2626 2627 <para> 2628 You can allocate a private data in this callback, as described 2629 in <link linkend="pcm-interface-runtime-private"><citetitle> 2630 Private Data</citetitle></link> section. 2631 </para> 2632 2633 <para> 2634 If the hardware configuration needs more constraints, set the 2635 hardware constraints here, too. 2636 See <link linkend="pcm-interface-constraints"><citetitle> 2637 Constraints</citetitle></link> for more details. 2638 </para> 2639 </section> 2640 2641 <section id="pcm-interface-operators-close-callback"> 2642 <title>close callback</title> 2643 <para> 2644 <informalexample> 2645 <programlisting> 2646<![CDATA[ 2647 static int snd_xxx_close(struct snd_pcm_substream *substream); 2648]]> 2649 </programlisting> 2650 </informalexample> 2651 2652 Obviously, this is called when a pcm substream is closed. 2653 </para> 2654 2655 <para> 2656 Any private instance for a pcm substream allocated in the 2657 open callback will be released here. 2658 2659 <informalexample> 2660 <programlisting> 2661<![CDATA[ 2662 static int snd_xxx_close(struct snd_pcm_substream *substream) 2663 { 2664 .... 2665 kfree(substream->runtime->private_data); 2666 .... 2667 } 2668]]> 2669 </programlisting> 2670 </informalexample> 2671 </para> 2672 </section> 2673 2674 <section id="pcm-interface-operators-ioctl-callback"> 2675 <title>ioctl callback</title> 2676 <para> 2677 This is used for any special call to pcm ioctls. But 2678 usually you can pass a generic ioctl callback, 2679 <function>snd_pcm_lib_ioctl</function>. 2680 </para> 2681 </section> 2682 2683 <section id="pcm-interface-operators-hw-params-callback"> 2684 <title>hw_params callback</title> 2685 <para> 2686 <informalexample> 2687 <programlisting> 2688<![CDATA[ 2689 static int snd_xxx_hw_params(struct snd_pcm_substream *substream, 2690 struct snd_pcm_hw_params *hw_params); 2691]]> 2692 </programlisting> 2693 </informalexample> 2694 </para> 2695 2696 <para> 2697 This is called when the hardware parameter 2698 (<structfield>hw_params</structfield>) is set 2699 up by the application, 2700 that is, once when the buffer size, the period size, the 2701 format, etc. are defined for the pcm substream. 2702 </para> 2703 2704 <para> 2705 Many hardware setups should be done in this callback, 2706 including the allocation of buffers. 2707 </para> 2708 2709 <para> 2710 Parameters to be initialized are retrieved by 2711 <function>params_xxx()</function> macros. To allocate 2712 buffer, you can call a helper function, 2713 2714 <informalexample> 2715 <programlisting> 2716<![CDATA[ 2717 snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params)); 2718]]> 2719 </programlisting> 2720 </informalexample> 2721 2722 <function>snd_pcm_lib_malloc_pages()</function> is available 2723 only when the DMA buffers have been pre-allocated. 2724 See the section <link 2725 linkend="buffer-and-memory-buffer-types"><citetitle> 2726 Buffer Types</citetitle></link> for more details. 2727 </para> 2728 2729 <para> 2730 Note that this and <structfield>prepare</structfield> callbacks 2731 may be called multiple times per initialization. 2732 For example, the OSS emulation may 2733 call these callbacks at each change via its ioctl. 2734 </para> 2735 2736 <para> 2737 Thus, you need to be careful not to allocate the same buffers 2738 many times, which will lead to memory leaks! Calling the 2739 helper function above many times is OK. It will release the 2740 previous buffer automatically when it was already allocated. 2741 </para> 2742 2743 <para> 2744 Another note is that this callback is non-atomic 2745 (schedulable) as default, i.e. when no 2746 <structfield>nonatomic</structfield> flag set. 2747 This is important, because the 2748 <structfield>trigger</structfield> callback 2749 is atomic (non-schedulable). That is, mutexes or any 2750 schedule-related functions are not available in 2751 <structfield>trigger</structfield> callback. 2752 Please see the subsection 2753 <link linkend="pcm-interface-atomicity"><citetitle> 2754 Atomicity</citetitle></link> for details. 2755 </para> 2756 </section> 2757 2758 <section id="pcm-interface-operators-hw-free-callback"> 2759 <title>hw_free callback</title> 2760 <para> 2761 <informalexample> 2762 <programlisting> 2763<![CDATA[ 2764 static int snd_xxx_hw_free(struct snd_pcm_substream *substream); 2765]]> 2766 </programlisting> 2767 </informalexample> 2768 </para> 2769 2770 <para> 2771 This is called to release the resources allocated via 2772 <structfield>hw_params</structfield>. For example, releasing the 2773 buffer via 2774 <function>snd_pcm_lib_malloc_pages()</function> is done by 2775 calling the following: 2776 2777 <informalexample> 2778 <programlisting> 2779<![CDATA[ 2780 snd_pcm_lib_free_pages(substream); 2781]]> 2782 </programlisting> 2783 </informalexample> 2784 </para> 2785 2786 <para> 2787 This function is always called before the close callback is called. 2788 Also, the callback may be called multiple times, too. 2789 Keep track whether the resource was already released. 2790 </para> 2791 </section> 2792 2793 <section id="pcm-interface-operators-prepare-callback"> 2794 <title>prepare callback</title> 2795 <para> 2796 <informalexample> 2797 <programlisting> 2798<![CDATA[ 2799 static int snd_xxx_prepare(struct snd_pcm_substream *substream); 2800]]> 2801 </programlisting> 2802 </informalexample> 2803 </para> 2804 2805 <para> 2806 This callback is called when the pcm is 2807 <quote>prepared</quote>. You can set the format type, sample 2808 rate, etc. here. The difference from 2809 <structfield>hw_params</structfield> is that the 2810 <structfield>prepare</structfield> callback will be called each 2811 time 2812 <function>snd_pcm_prepare()</function> is called, i.e. when 2813 recovering after underruns, etc. 2814 </para> 2815 2816 <para> 2817 Note that this callback is now non-atomic. 2818 You can use schedule-related functions safely in this callback. 2819 </para> 2820 2821 <para> 2822 In this and the following callbacks, you can refer to the 2823 values via the runtime record, 2824 substream->runtime. 2825 For example, to get the current 2826 rate, format or channels, access to 2827 runtime->rate, 2828 runtime->format or 2829 runtime->channels, respectively. 2830 The physical address of the allocated buffer is set to 2831 runtime->dma_area. The buffer and period sizes are 2832 in runtime->buffer_size and runtime->period_size, 2833 respectively. 2834 </para> 2835 2836 <para> 2837 Be careful that this callback will be called many times at 2838 each setup, too. 2839 </para> 2840 </section> 2841 2842 <section id="pcm-interface-operators-trigger-callback"> 2843 <title>trigger callback</title> 2844 <para> 2845 <informalexample> 2846 <programlisting> 2847<![CDATA[ 2848 static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd); 2849]]> 2850 </programlisting> 2851 </informalexample> 2852 2853 This is called when the pcm is started, stopped or paused. 2854 </para> 2855 2856 <para> 2857 Which action is specified in the second argument, 2858 <constant>SNDRV_PCM_TRIGGER_XXX</constant> in 2859 <filename><sound/pcm.h></filename>. At least, 2860 the <constant>START</constant> and <constant>STOP</constant> 2861 commands must be defined in this callback. 2862 2863 <informalexample> 2864 <programlisting> 2865<![CDATA[ 2866 switch (cmd) { 2867 case SNDRV_PCM_TRIGGER_START: 2868 /* do something to start the PCM engine */ 2869 break; 2870 case SNDRV_PCM_TRIGGER_STOP: 2871 /* do something to stop the PCM engine */ 2872 break; 2873 default: 2874 return -EINVAL; 2875 } 2876]]> 2877 </programlisting> 2878 </informalexample> 2879 </para> 2880 2881 <para> 2882 When the pcm supports the pause operation (given in the info 2883 field of the hardware table), the <constant>PAUSE_PUSH</constant> 2884 and <constant>PAUSE_RELEASE</constant> commands must be 2885 handled here, too. The former is the command to pause the pcm, 2886 and the latter to restart the pcm again. 2887 </para> 2888 2889 <para> 2890 When the pcm supports the suspend/resume operation, 2891 regardless of full or partial suspend/resume support, 2892 the <constant>SUSPEND</constant> and <constant>RESUME</constant> 2893 commands must be handled, too. 2894 These commands are issued when the power-management status is 2895 changed. Obviously, the <constant>SUSPEND</constant> and 2896 <constant>RESUME</constant> commands 2897 suspend and resume the pcm substream, and usually, they 2898 are identical to the <constant>STOP</constant> and 2899 <constant>START</constant> commands, respectively. 2900 See the <link linkend="power-management"><citetitle> 2901 Power Management</citetitle></link> section for details. 2902 </para> 2903 2904 <para> 2905 As mentioned, this callback is atomic as default unless 2906 <structfield>nonatomic</structfield> flag set, and 2907 you cannot call functions which may sleep. 2908 The trigger callback should be as minimal as possible, 2909 just really triggering the DMA. The other stuff should be 2910 initialized hw_params and prepare callbacks properly 2911 beforehand. 2912 </para> 2913 </section> 2914 2915 <section id="pcm-interface-operators-pointer-callback"> 2916 <title>pointer callback</title> 2917 <para> 2918 <informalexample> 2919 <programlisting> 2920<![CDATA[ 2921 static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream) 2922]]> 2923 </programlisting> 2924 </informalexample> 2925 2926 This callback is called when the PCM middle layer inquires 2927 the current hardware position on the buffer. The position must 2928 be returned in frames, 2929 ranging from 0 to buffer_size - 1. 2930 </para> 2931 2932 <para> 2933 This is called usually from the buffer-update routine in the 2934 pcm middle layer, which is invoked when 2935 <function>snd_pcm_period_elapsed()</function> is called in the 2936 interrupt routine. Then the pcm middle layer updates the 2937 position and calculates the available space, and wakes up the 2938 sleeping poll threads, etc. 2939 </para> 2940 2941 <para> 2942 This callback is also atomic as default. 2943 </para> 2944 </section> 2945 2946 <section id="pcm-interface-operators-copy-silence"> 2947 <title>copy and silence callbacks</title> 2948 <para> 2949 These callbacks are not mandatory, and can be omitted in 2950 most cases. These callbacks are used when the hardware buffer 2951 cannot be in the normal memory space. Some chips have their 2952 own buffer on the hardware which is not mappable. In such a 2953 case, you have to transfer the data manually from the memory 2954 buffer to the hardware buffer. Or, if the buffer is 2955 non-contiguous on both physical and virtual memory spaces, 2956 these callbacks must be defined, too. 2957 </para> 2958 2959 <para> 2960 If these two callbacks are defined, copy and set-silence 2961 operations are done by them. The detailed will be described in 2962 the later section <link 2963 linkend="buffer-and-memory"><citetitle>Buffer and Memory 2964 Management</citetitle></link>. 2965 </para> 2966 </section> 2967 2968 <section id="pcm-interface-operators-ack"> 2969 <title>ack callback</title> 2970 <para> 2971 This callback is also not mandatory. This callback is called 2972 when the appl_ptr is updated in read or write operations. 2973 Some drivers like emu10k1-fx and cs46xx need to track the 2974 current appl_ptr for the internal buffer, and this callback 2975 is useful only for such a purpose. 2976 </para> 2977 <para> 2978 This callback is atomic as default. 2979 </para> 2980 </section> 2981 2982 <section id="pcm-interface-operators-page-callback"> 2983 <title>page callback</title> 2984 2985 <para> 2986 This callback is optional too. This callback is used 2987 mainly for non-contiguous buffers. The mmap calls this 2988 callback to get the page address. Some examples will be 2989 explained in the later section <link 2990 linkend="buffer-and-memory"><citetitle>Buffer and Memory 2991 Management</citetitle></link>, too. 2992 </para> 2993 </section> 2994 </section> 2995 2996 <section id="pcm-interface-interrupt-handler"> 2997 <title>Interrupt Handler</title> 2998 <para> 2999 The rest of pcm stuff is the PCM interrupt handler. The 3000 role of PCM interrupt handler in the sound driver is to update 3001 the buffer position and to tell the PCM middle layer when the 3002 buffer position goes across the prescribed period size. To 3003 inform this, call the <function>snd_pcm_period_elapsed()</function> 3004 function. 3005 </para> 3006 3007 <para> 3008 There are several types of sound chips to generate the interrupts. 3009 </para> 3010 3011 <section id="pcm-interface-interrupt-handler-boundary"> 3012 <title>Interrupts at the period (fragment) boundary</title> 3013 <para> 3014 This is the most frequently found type: the hardware 3015 generates an interrupt at each period boundary. 3016 In this case, you can call 3017 <function>snd_pcm_period_elapsed()</function> at each 3018 interrupt. 3019 </para> 3020 3021 <para> 3022 <function>snd_pcm_period_elapsed()</function> takes the 3023 substream pointer as its argument. Thus, you need to keep the 3024 substream pointer accessible from the chip instance. For 3025 example, define substream field in the chip record to hold the 3026 current running substream pointer, and set the pointer value 3027 at open callback (and reset at close callback). 3028 </para> 3029 3030 <para> 3031 If you acquire a spinlock in the interrupt handler, and the 3032 lock is used in other pcm callbacks, too, then you have to 3033 release the lock before calling 3034 <function>snd_pcm_period_elapsed()</function>, because 3035 <function>snd_pcm_period_elapsed()</function> calls other pcm 3036 callbacks inside. 3037 </para> 3038 3039 <para> 3040 Typical code would be like: 3041 3042 <example> 3043 <title>Interrupt Handler Case #1</title> 3044 <programlisting> 3045<![CDATA[ 3046 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id) 3047 { 3048 struct mychip *chip = dev_id; 3049 spin_lock(&chip->lock); 3050 .... 3051 if (pcm_irq_invoked(chip)) { 3052 /* call updater, unlock before it */ 3053 spin_unlock(&chip->lock); 3054 snd_pcm_period_elapsed(chip->substream); 3055 spin_lock(&chip->lock); 3056 /* acknowledge the interrupt if necessary */ 3057 } 3058 .... 3059 spin_unlock(&chip->lock); 3060 return IRQ_HANDLED; 3061 } 3062]]> 3063 </programlisting> 3064 </example> 3065 </para> 3066 </section> 3067 3068 <section id="pcm-interface-interrupt-handler-timer"> 3069 <title>High frequency timer interrupts</title> 3070 <para> 3071 This happens when the hardware doesn't generate interrupts 3072 at the period boundary but issues timer interrupts at a fixed 3073 timer rate (e.g. es1968 or ymfpci drivers). 3074 In this case, you need to check the current hardware 3075 position and accumulate the processed sample length at each 3076 interrupt. When the accumulated size exceeds the period 3077 size, call 3078 <function>snd_pcm_period_elapsed()</function> and reset the 3079 accumulator. 3080 </para> 3081 3082 <para> 3083 Typical code would be like the following. 3084 3085 <example> 3086 <title>Interrupt Handler Case #2</title> 3087 <programlisting> 3088<![CDATA[ 3089 static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id) 3090 { 3091 struct mychip *chip = dev_id; 3092 spin_lock(&chip->lock); 3093 .... 3094 if (pcm_irq_invoked(chip)) { 3095 unsigned int last_ptr, size; 3096 /* get the current hardware pointer (in frames) */ 3097 last_ptr = get_hw_ptr(chip); 3098 /* calculate the processed frames since the 3099 * last update 3100 */ 3101 if (last_ptr < chip->last_ptr) 3102 size = runtime->buffer_size + last_ptr 3103 - chip->last_ptr; 3104 else 3105 size = last_ptr - chip->last_ptr; 3106 /* remember the last updated point */ 3107 chip->last_ptr = last_ptr; 3108 /* accumulate the size */ 3109 chip->size += size; 3110 /* over the period boundary? */ 3111 if (chip->size >= runtime->period_size) { 3112 /* reset the accumulator */ 3113 chip->size %= runtime->period_size; 3114 /* call updater */ 3115 spin_unlock(&chip->lock); 3116 snd_pcm_period_elapsed(substream); 3117 spin_lock(&chip->lock); 3118 } 3119 /* acknowledge the interrupt if necessary */ 3120 } 3121 .... 3122 spin_unlock(&chip->lock); 3123 return IRQ_HANDLED; 3124 } 3125]]> 3126 </programlisting> 3127 </example> 3128 </para> 3129 </section> 3130 3131 <section id="pcm-interface-interrupt-handler-both"> 3132 <title>On calling <function>snd_pcm_period_elapsed()</function></title> 3133 <para> 3134 In both cases, even if more than one period are elapsed, you 3135 don't have to call 3136 <function>snd_pcm_period_elapsed()</function> many times. Call 3137 only once. And the pcm layer will check the current hardware 3138 pointer and update to the latest status. 3139 </para> 3140 </section> 3141 </section> 3142 3143 <section id="pcm-interface-atomicity"> 3144 <title>Atomicity</title> 3145 <para> 3146 One of the most important (and thus difficult to debug) problems 3147 in kernel programming are race conditions. 3148 In the Linux kernel, they are usually avoided via spin-locks, mutexes 3149 or semaphores. In general, if a race condition can happen 3150 in an interrupt handler, it has to be managed atomically, and you 3151 have to use a spinlock to protect the critical session. If the 3152 critical section is not in interrupt handler code and 3153 if taking a relatively long time to execute is acceptable, you 3154 should use mutexes or semaphores instead. 3155 </para> 3156 3157 <para> 3158 As already seen, some pcm callbacks are atomic and some are 3159 not. For example, the <parameter>hw_params</parameter> callback is 3160 non-atomic, while <parameter>trigger</parameter> callback is 3161 atomic. This means, the latter is called already in a spinlock 3162 held by the PCM middle layer. Please take this atomicity into 3163 account when you choose a locking scheme in the callbacks. 3164 </para> 3165 3166 <para> 3167 In the atomic callbacks, you cannot use functions which may call 3168 <function>schedule</function> or go to 3169 <function>sleep</function>. Semaphores and mutexes can sleep, 3170 and hence they cannot be used inside the atomic callbacks 3171 (e.g. <parameter>trigger</parameter> callback). 3172 To implement some delay in such a callback, please use 3173 <function>udelay()</function> or <function>mdelay()</function>. 3174 </para> 3175 3176 <para> 3177 All three atomic callbacks (trigger, pointer, and ack) are 3178 called with local interrupts disabled. 3179 </para> 3180 3181 <para> 3182 The recent changes in PCM core code, however, allow all PCM 3183 operations to be non-atomic. This assumes that the all caller 3184 sides are in non-atomic contexts. For example, the function 3185 <function>snd_pcm_period_elapsed()</function> is called 3186 typically from the interrupt handler. But, if you set up the 3187 driver to use a threaded interrupt handler, this call can be in 3188 non-atomic context, too. In such a case, you can set 3189 <structfield>nonatomic</structfield> filed of 3190 <structname>snd_pcm</structname> object after creating it. 3191 When this flag is set, mutex and rwsem are used internally in 3192 the PCM core instead of spin and rwlocks, so that you can call 3193 all PCM functions safely in a non-atomic context. 3194 </para> 3195 3196 </section> 3197 <section id="pcm-interface-constraints"> 3198 <title>Constraints</title> 3199 <para> 3200 If your chip supports unconventional sample rates, or only the 3201 limited samples, you need to set a constraint for the 3202 condition. 3203 </para> 3204 3205 <para> 3206 For example, in order to restrict the sample rates in the some 3207 supported values, use 3208 <function>snd_pcm_hw_constraint_list()</function>. 3209 You need to call this function in the open callback. 3210 3211 <example> 3212 <title>Example of Hardware Constraints</title> 3213 <programlisting> 3214<![CDATA[ 3215 static unsigned int rates[] = 3216 {4000, 10000, 22050, 44100}; 3217 static struct snd_pcm_hw_constraint_list constraints_rates = { 3218 .count = ARRAY_SIZE(rates), 3219 .list = rates, 3220 .mask = 0, 3221 }; 3222 3223 static int snd_mychip_pcm_open(struct snd_pcm_substream *substream) 3224 { 3225 int err; 3226 .... 3227 err = snd_pcm_hw_constraint_list(substream->runtime, 0, 3228 SNDRV_PCM_HW_PARAM_RATE, 3229 &constraints_rates); 3230 if (err < 0) 3231 return err; 3232 .... 3233 } 3234]]> 3235 </programlisting> 3236 </example> 3237 </para> 3238 3239 <para> 3240 There are many different constraints. 3241 Look at <filename>sound/pcm.h</filename> for a complete list. 3242 You can even define your own constraint rules. 3243 For example, let's suppose my_chip can manage a substream of 1 channel 3244 if and only if the format is S16_LE, otherwise it supports any format 3245 specified in the <structname>snd_pcm_hardware</structname> structure (or in any 3246 other constraint_list). You can build a rule like this: 3247 3248 <example> 3249 <title>Example of Hardware Constraints for Channels</title> 3250 <programlisting> 3251<![CDATA[ 3252 static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params, 3253 struct snd_pcm_hw_rule *rule) 3254 { 3255 struct snd_interval *c = hw_param_interval(params, 3256 SNDRV_PCM_HW_PARAM_CHANNELS); 3257 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT); 3258 struct snd_interval ch; 3259 3260 snd_interval_any(&ch); 3261 if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) { 3262 ch.min = ch.max = 1; 3263 ch.integer = 1; 3264 return snd_interval_refine(c, &ch); 3265 } 3266 return 0; 3267 } 3268]]> 3269 </programlisting> 3270 </example> 3271 </para> 3272 3273 <para> 3274 Then you need to call this function to add your rule: 3275 3276 <informalexample> 3277 <programlisting> 3278<![CDATA[ 3279 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS, 3280 hw_rule_channels_by_format, NULL, 3281 SNDRV_PCM_HW_PARAM_FORMAT, -1); 3282]]> 3283 </programlisting> 3284 </informalexample> 3285 </para> 3286 3287 <para> 3288 The rule function is called when an application sets the PCM 3289 format, and it refines the number of channels accordingly. 3290 But an application may set the number of channels before 3291 setting the format. Thus you also need to define the inverse rule: 3292 3293 <example> 3294 <title>Example of Hardware Constraints for Formats</title> 3295 <programlisting> 3296<![CDATA[ 3297 static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params, 3298 struct snd_pcm_hw_rule *rule) 3299 { 3300 struct snd_interval *c = hw_param_interval(params, 3301 SNDRV_PCM_HW_PARAM_CHANNELS); 3302 struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT); 3303 struct snd_mask fmt; 3304 3305 snd_mask_any(&fmt); /* Init the struct */ 3306 if (c->min < 2) { 3307 fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE; 3308 return snd_mask_refine(f, &fmt); 3309 } 3310 return 0; 3311 } 3312]]> 3313 </programlisting> 3314 </example> 3315 </para> 3316 3317 <para> 3318 ...and in the open callback: 3319 <informalexample> 3320 <programlisting> 3321<![CDATA[ 3322 snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT, 3323 hw_rule_format_by_channels, NULL, 3324 SNDRV_PCM_HW_PARAM_CHANNELS, -1); 3325]]> 3326 </programlisting> 3327 </informalexample> 3328 </para> 3329 3330 <para> 3331 I won't give more details here, rather I 3332 would like to say, <quote>Luke, use the source.</quote> 3333 </para> 3334 </section> 3335 3336 </chapter> 3337 3338 3339<!-- ****************************************************** --> 3340<!-- Control Interface --> 3341<!-- ****************************************************** --> 3342 <chapter id="control-interface"> 3343 <title>Control Interface</title> 3344 3345 <section id="control-interface-general"> 3346 <title>General</title> 3347 <para> 3348 The control interface is used widely for many switches, 3349 sliders, etc. which are accessed from user-space. Its most 3350 important use is the mixer interface. In other words, since ALSA 3351 0.9.x, all the mixer stuff is implemented on the control kernel API. 3352 </para> 3353 3354 <para> 3355 ALSA has a well-defined AC97 control module. If your chip 3356 supports only the AC97 and nothing else, you can skip this 3357 section. 3358 </para> 3359 3360 <para> 3361 The control API is defined in 3362 <filename><sound/control.h></filename>. 3363 Include this file if you want to add your own controls. 3364 </para> 3365 </section> 3366 3367 <section id="control-interface-definition"> 3368 <title>Definition of Controls</title> 3369 <para> 3370 To create a new control, you need to define the 3371 following three 3372 callbacks: <structfield>info</structfield>, 3373 <structfield>get</structfield> and 3374 <structfield>put</structfield>. Then, define a 3375 struct <structname>snd_kcontrol_new</structname> record, such as: 3376 3377 <example> 3378 <title>Definition of a Control</title> 3379 <programlisting> 3380<![CDATA[ 3381 static struct snd_kcontrol_new my_control = { 3382 .iface = SNDRV_CTL_ELEM_IFACE_MIXER, 3383 .name = "PCM Playback Switch", 3384 .index = 0, 3385 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE, 3386 .private_value = 0xffff, 3387 .info = my_control_info, 3388 .get = my_control_get, 3389 .put = my_control_put 3390 }; 3391]]> 3392 </programlisting> 3393 </example> 3394 </para> 3395 3396 <para> 3397 The <structfield>iface</structfield> field specifies the control 3398 type, <constant>SNDRV_CTL_ELEM_IFACE_XXX</constant>, which 3399 is usually <constant>MIXER</constant>. 3400 Use <constant>CARD</constant> for global controls that are not 3401 logically part of the mixer. 3402 If the control is closely associated with some specific device on 3403 the sound card, use <constant>HWDEP</constant>, 3404 <constant>PCM</constant>, <constant>RAWMIDI</constant>, 3405 <constant>TIMER</constant>, or <constant>SEQUENCER</constant>, and 3406 specify the device number with the 3407 <structfield>device</structfield> and 3408 <structfield>subdevice</structfield> fields. 3409 </para> 3410 3411 <para> 3412 The <structfield>name</structfield> is the name identifier 3413 string. Since ALSA 0.9.x, the control name is very important, 3414 because its role is classified from its name. There are 3415 pre-defined standard control names. The details are described in 3416 the <link linkend="control-interface-control-names"><citetitle> 3417 Control Names</citetitle></link> subsection. 3418 </para> 3419 3420 <para> 3421 The <structfield>index</structfield> field holds the index number 3422 of this control. If there are several different controls with 3423 the same name, they can be distinguished by the index 3424 number. This is the case when 3425 several codecs exist on the card. If the index is zero, you can 3426 omit the definition above. 3427 </para> 3428 3429 <para> 3430 The <structfield>access</structfield> field contains the access 3431 type of this control. Give the combination of bit masks, 3432 <constant>SNDRV_CTL_ELEM_ACCESS_XXX</constant>, there. 3433 The details will be explained in 3434 the <link linkend="control-interface-access-flags"><citetitle> 3435 Access Flags</citetitle></link> subsection. 3436 </para> 3437 3438 <para> 3439 The <structfield>private_value</structfield> field contains 3440 an arbitrary long integer value for this record. When using 3441 the generic <structfield>info</structfield>, 3442 <structfield>get</structfield> and 3443 <structfield>put</structfield> callbacks, you can pass a value 3444 through this field. If several small numbers are necessary, you can 3445 combine them in bitwise. Or, it's possible to give a pointer 3446 (casted to unsigned long) of some record to this field, too. 3447 </para> 3448 3449 <para> 3450 The <structfield>tlv</structfield> field can be used to provide 3451 metadata about the control; see the 3452 <link linkend="control-interface-tlv"> 3453 <citetitle>Metadata</citetitle></link> subsection. 3454 </para> 3455 3456 <para> 3457 The other three are 3458 <link linkend="control-interface-callbacks"><citetitle> 3459 callback functions</citetitle></link>. 3460 </para> 3461 </section> 3462 3463 <section id="control-interface-control-names"> 3464 <title>Control Names</title> 3465 <para> 3466 There are some standards to define the control names. A 3467 control is usually defined from the three parts as 3468 <quote>SOURCE DIRECTION FUNCTION</quote>. 3469 </para> 3470 3471 <para> 3472 The first, <constant>SOURCE</constant>, specifies the source 3473 of the control, and is a string such as <quote>Master</quote>, 3474 <quote>PCM</quote>, <quote>CD</quote> and 3475 <quote>Line</quote>. There are many pre-defined sources. 3476 </para> 3477 3478 <para> 3479 The second, <constant>DIRECTION</constant>, is one of the 3480 following strings according to the direction of the control: 3481 <quote>Playback</quote>, <quote>Capture</quote>, <quote>Bypass 3482 Playback</quote> and <quote>Bypass Capture</quote>. Or, it can 3483 be omitted, meaning both playback and capture directions. 3484 </para> 3485 3486 <para> 3487 The third, <constant>FUNCTION</constant>, is one of the 3488 following strings according to the function of the control: 3489 <quote>Switch</quote>, <quote>Volume</quote> and 3490 <quote>Route</quote>. 3491 </para> 3492 3493 <para> 3494 The example of control names are, thus, <quote>Master Capture 3495 Switch</quote> or <quote>PCM Playback Volume</quote>. 3496 </para> 3497 3498 <para> 3499 There are some exceptions: 3500 </para> 3501 3502 <section id="control-interface-control-names-global"> 3503 <title>Global capture and playback</title> 3504 <para> 3505 <quote>Capture Source</quote>, <quote>Capture Switch</quote> 3506 and <quote>Capture Volume</quote> are used for the global 3507 capture (input) source, switch and volume. Similarly, 3508 <quote>Playback Switch</quote> and <quote>Playback 3509 Volume</quote> are used for the global output gain switch and 3510 volume. 3511 </para> 3512 </section> 3513 3514 <section id="control-interface-control-names-tone"> 3515 <title>Tone-controls</title> 3516 <para> 3517 tone-control switch and volumes are specified like 3518 <quote>Tone Control - XXX</quote>, e.g. <quote>Tone Control - 3519 Switch</quote>, <quote>Tone Control - Bass</quote>, 3520 <quote>Tone Control - Center</quote>. 3521 </para> 3522 </section> 3523 3524 <section id="control-interface-control-names-3d"> 3525 <title>3D controls</title> 3526 <para> 3527 3D-control switches and volumes are specified like <quote>3D 3528 Control - XXX</quote>, e.g. <quote>3D Control - 3529 Switch</quote>, <quote>3D Control - Center</quote>, <quote>3D 3530 Control - Space</quote>. 3531 </para> 3532 </section> 3533 3534 <section id="control-interface-control-names-mic"> 3535 <title>Mic boost</title> 3536 <para> 3537 Mic-boost switch is set as <quote>Mic Boost</quote> or 3538 <quote>Mic Boost (6dB)</quote>. 3539 </para> 3540 3541 <para> 3542 More precise information can be found in 3543 <filename>Documentation/sound/alsa/ControlNames.txt</filename>. 3544 </para> 3545 </section> 3546 </section> 3547 3548 <section id="control-interface-access-flags"> 3549 <title>Access Flags</title> 3550 3551 <para> 3552 The access flag is the bitmask which specifies the access type 3553 of the given control. The default access type is 3554 <constant>SNDRV_CTL_ELEM_ACCESS_READWRITE</constant>, 3555 which means both read and write are allowed to this control. 3556 When the access flag is omitted (i.e. = 0), it is 3557 considered as <constant>READWRITE</constant> access as default. 3558 </para> 3559 3560 <para> 3561 When the control is read-only, pass 3562 <constant>SNDRV_CTL_ELEM_ACCESS_READ</constant> instead. 3563 In this case, you don't have to define 3564 the <structfield>put</structfield> callback. 3565 Similarly, when the control is write-only (although it's a rare 3566 case), you can use the <constant>WRITE</constant> flag instead, and 3567 you don't need the <structfield>get</structfield> callback. 3568 </para> 3569 3570 <para> 3571 If the control value changes frequently (e.g. the VU meter), 3572 <constant>VOLATILE</constant> flag should be given. This means 3573 that the control may be changed without 3574 <link linkend="control-interface-change-notification"><citetitle> 3575 notification</citetitle></link>. Applications should poll such 3576 a control constantly. 3577 </para> 3578 3579 <para> 3580 When the control is inactive, set 3581 the <constant>INACTIVE</constant> flag, too. 3582 There are <constant>LOCK</constant> and 3583 <constant>OWNER</constant> flags to change the write 3584 permissions. 3585 </para> 3586 3587 </section> 3588 3589 <section id="control-interface-callbacks"> 3590 <title>Callbacks</title> 3591 3592 <section id="control-interface-callbacks-info"> 3593 <title>info callback</title> 3594 <para> 3595 The <structfield>info</structfield> callback is used to get 3596 detailed information on this control. This must store the 3597 values of the given struct <structname>snd_ctl_elem_info</structname> 3598 object. For example, for a boolean control with a single 3599 element: 3600 3601 <example> 3602 <title>Example of info callback</title> 3603 <programlisting> 3604<![CDATA[ 3605 static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol, 3606 struct snd_ctl_elem_info *uinfo) 3607 { 3608 uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN; 3609 uinfo->count = 1; 3610 uinfo->value.integer.min = 0; 3611 uinfo->value.integer.max = 1; 3612 return 0; 3613 } 3614]]> 3615 </programlisting> 3616 </example> 3617 </para> 3618 3619 <para> 3620 The <structfield>type</structfield> field specifies the type 3621 of the control. There are <constant>BOOLEAN</constant>, 3622 <constant>INTEGER</constant>, <constant>ENUMERATED</constant>, 3623 <constant>BYTES</constant>, <constant>IEC958</constant> and 3624 <constant>INTEGER64</constant>. The 3625 <structfield>count</structfield> field specifies the 3626 number of elements in this control. For example, a stereo 3627 volume would have count = 2. The 3628 <structfield>value</structfield> field is a union, and 3629 the values stored are depending on the type. The boolean and 3630 integer types are identical. 3631 </para> 3632 3633 <para> 3634 The enumerated type is a bit different from others. You'll 3635 need to set the string for the currently given item index. 3636 3637 <informalexample> 3638 <programlisting> 3639<![CDATA[ 3640 static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol, 3641 struct snd_ctl_elem_info *uinfo) 3642 { 3643 static char *texts[4] = { 3644 "First", "Second", "Third", "Fourth" 3645 }; 3646 uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED; 3647 uinfo->count = 1; 3648 uinfo->value.enumerated.items = 4; 3649 if (uinfo->value.enumerated.item > 3) 3650 uinfo->value.enumerated.item = 3; 3651 strcpy(uinfo->value.enumerated.name, 3652 texts[uinfo->value.enumerated.item]); 3653 return 0; 3654 } 3655]]> 3656 </programlisting> 3657 </informalexample> 3658 </para> 3659 3660 <para> 3661 The above callback can be simplified with a helper function, 3662 <function>snd_ctl_enum_info</function>. The final code 3663 looks like below. 3664 (You can pass ARRAY_SIZE(texts) instead of 4 in the third 3665 argument; it's a matter of taste.) 3666 3667 <informalexample> 3668 <programlisting> 3669<![CDATA[ 3670 static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol, 3671 struct snd_ctl_elem_info *uinfo) 3672 { 3673 static char *texts[4] = { 3674 "First", "Second", "Third", "Fourth" 3675 }; 3676 return snd_ctl_enum_info(uinfo, 1, 4, texts); 3677 } 3678]]> 3679 </programlisting> 3680 </informalexample> 3681 </para> 3682 3683 <para> 3684 Some common info callbacks are available for your convenience: 3685 <function>snd_ctl_boolean_mono_info()</function> and 3686 <function>snd_ctl_boolean_stereo_info()</function>. 3687 Obviously, the former is an info callback for a mono channel 3688 boolean item, just like <function>snd_myctl_mono_info</function> 3689 above, and the latter is for a stereo channel boolean item. 3690 </para> 3691 3692 </section> 3693 3694 <section id="control-interface-callbacks-get"> 3695 <title>get callback</title> 3696 3697 <para> 3698 This callback is used to read the current value of the 3699 control and to return to user-space. 3700 </para> 3701 3702 <para> 3703 For example, 3704 3705 <example> 3706 <title>Example of get callback</title> 3707 <programlisting> 3708<![CDATA[ 3709 static int snd_myctl_get(struct snd_kcontrol *kcontrol, 3710 struct snd_ctl_elem_value *ucontrol) 3711 { 3712 struct mychip *chip = snd_kcontrol_chip(kcontrol); 3713 ucontrol->value.integer.value[0] = get_some_value(chip); 3714 return 0; 3715 } 3716]]> 3717 </programlisting> 3718 </example> 3719 </para> 3720 3721 <para> 3722 The <structfield>value</structfield> field depends on 3723 the type of control as well as on the info callback. For example, 3724 the sb driver uses this field to store the register offset, 3725 the bit-shift and the bit-mask. The 3726 <structfield>private_value</structfield> field is set as follows: 3727 <informalexample> 3728 <programlisting> 3729<![CDATA[ 3730 .private_value = reg | (shift << 16) | (mask << 24) 3731]]> 3732 </programlisting> 3733 </informalexample> 3734 and is retrieved in callbacks like 3735 <informalexample> 3736 <programlisting> 3737<![CDATA[ 3738 static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol, 3739 struct snd_ctl_elem_value *ucontrol) 3740 { 3741 int reg = kcontrol->private_value & 0xff; 3742 int shift = (kcontrol->private_value >> 16) & 0xff; 3743 int mask = (kcontrol->private_value >> 24) & 0xff; 3744 .... 3745 } 3746]]> 3747 </programlisting> 3748 </informalexample> 3749 </para> 3750 3751 <para> 3752 In the <structfield>get</structfield> callback, 3753 you have to fill all the elements if the 3754 control has more than one elements, 3755 i.e. <structfield>count</structfield> > 1. 3756 In the example above, we filled only one element 3757 (<structfield>value.integer.value[0]</structfield>) since it's 3758 assumed as <structfield>count</structfield> = 1. 3759 </para> 3760 </section> 3761 3762 <section id="control-interface-callbacks-put"> 3763 <title>put callback</title> 3764 3765 <para> 3766 This callback is used to write a value from user-space. 3767 </para> 3768 3769 <para> 3770 For example, 3771 3772 <example> 3773 <title>Example of put callback</title> 3774 <programlisting> 3775<![CDATA[ 3776 static int snd_myctl_put(struct snd_kcontrol *kcontrol, 3777 struct snd_ctl_elem_value *ucontrol) 3778 { 3779 struct mychip *chip = snd_kcontrol_chip(kcontrol); 3780 int changed = 0; 3781 if (chip->current_value != 3782 ucontrol->value.integer.value[0]) { 3783 change_current_value(chip, 3784 ucontrol->value.integer.value[0]); 3785 changed = 1; 3786 } 3787 return changed; 3788 } 3789]]> 3790 </programlisting> 3791 </example> 3792 3793 As seen above, you have to return 1 if the value is 3794 changed. If the value is not changed, return 0 instead. 3795 If any fatal error happens, return a negative error code as 3796 usual. 3797 </para> 3798 3799 <para> 3800 As in the <structfield>get</structfield> callback, 3801 when the control has more than one elements, 3802 all elements must be evaluated in this callback, too. 3803 </para> 3804 </section> 3805 3806 <section id="control-interface-callbacks-all"> 3807 <title>Callbacks are not atomic</title> 3808 <para> 3809 All these three callbacks are basically not atomic. 3810 </para> 3811 </section> 3812 </section> 3813 3814 <section id="control-interface-constructor"> 3815 <title>Constructor</title> 3816 <para> 3817 When everything is ready, finally we can create a new 3818 control. To create a control, there are two functions to be 3819 called, <function>snd_ctl_new1()</function> and 3820 <function>snd_ctl_add()</function>. 3821 </para> 3822 3823 <para> 3824 In the simplest way, you can do like this: 3825 3826 <informalexample> 3827 <programlisting> 3828<![CDATA[ 3829 err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip)); 3830 if (err < 0) 3831 return err; 3832]]> 3833 </programlisting> 3834 </informalexample> 3835 3836 where <parameter>my_control</parameter> is the 3837 struct <structname>snd_kcontrol_new</structname> object defined above, and chip 3838 is the object pointer to be passed to 3839 kcontrol->private_data 3840 which can be referred to in callbacks. 3841 </para> 3842 3843 <para> 3844 <function>snd_ctl_new1()</function> allocates a new 3845 <structname>snd_kcontrol</structname> instance, 3846 and <function>snd_ctl_add</function> assigns the given 3847 control component to the card. 3848 </para> 3849 </section> 3850 3851 <section id="control-interface-change-notification"> 3852 <title>Change Notification</title> 3853 <para> 3854 If you need to change and update a control in the interrupt 3855 routine, you can call <function>snd_ctl_notify()</function>. For 3856 example, 3857 3858 <informalexample> 3859 <programlisting> 3860<![CDATA[ 3861 snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer); 3862]]> 3863 </programlisting> 3864 </informalexample> 3865 3866 This function takes the card pointer, the event-mask, and the 3867 control id pointer for the notification. The event-mask 3868 specifies the types of notification, for example, in the above 3869 example, the change of control values is notified. 3870 The id pointer is the pointer of struct <structname>snd_ctl_elem_id</structname> 3871 to be notified. 3872 You can find some examples in <filename>es1938.c</filename> or 3873 <filename>es1968.c</filename> for hardware volume interrupts. 3874 </para> 3875 </section> 3876 3877 <section id="control-interface-tlv"> 3878 <title>Metadata</title> 3879 <para> 3880 To provide information about the dB values of a mixer control, use 3881 on of the <constant>DECLARE_TLV_xxx</constant> macros from 3882 <filename><sound/tlv.h></filename> to define a variable 3883 containing this information, set the<structfield>tlv.p 3884 </structfield> field to point to this variable, and include the 3885 <constant>SNDRV_CTL_ELEM_ACCESS_TLV_READ</constant> flag in the 3886 <structfield>access</structfield> field; like this: 3887 <informalexample> 3888 <programlisting> 3889<![CDATA[ 3890 static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0); 3891 3892 static struct snd_kcontrol_new my_control = { 3893 ... 3894 .access = SNDRV_CTL_ELEM_ACCESS_READWRITE | 3895 SNDRV_CTL_ELEM_ACCESS_TLV_READ, 3896 ... 3897 .tlv.p = db_scale_my_control, 3898 }; 3899]]> 3900 </programlisting> 3901 </informalexample> 3902 </para> 3903 3904 <para> 3905 The <function>DECLARE_TLV_DB_SCALE</function> macro defines 3906 information about a mixer control where each step in the control's 3907 value changes the dB value by a constant dB amount. 3908 The first parameter is the name of the variable to be defined. 3909 The second parameter is the minimum value, in units of 0.01 dB. 3910 The third parameter is the step size, in units of 0.01 dB. 3911 Set the fourth parameter to 1 if the minimum value actually mutes 3912 the control. 3913 </para> 3914 3915 <para> 3916 The <function>DECLARE_TLV_DB_LINEAR</function> macro defines 3917 information about a mixer control where the control's value affects 3918 the output linearly. 3919 The first parameter is the name of the variable to be defined. 3920 The second parameter is the minimum value, in units of 0.01 dB. 3921 The third parameter is the maximum value, in units of 0.01 dB. 3922 If the minimum value mutes the control, set the second parameter to 3923 <constant>TLV_DB_GAIN_MUTE</constant>. 3924 </para> 3925 </section> 3926 3927 </chapter> 3928 3929 3930<!-- ****************************************************** --> 3931<!-- API for AC97 Codec --> 3932<!-- ****************************************************** --> 3933 <chapter id="api-ac97"> 3934 <title>API for AC97 Codec</title> 3935 3936 <section> 3937 <title>General</title> 3938 <para> 3939 The ALSA AC97 codec layer is a well-defined one, and you don't 3940 have to write much code to control it. Only low-level control 3941 routines are necessary. The AC97 codec API is defined in 3942 <filename><sound/ac97_codec.h></filename>. 3943 </para> 3944 </section> 3945 3946 <section id="api-ac97-example"> 3947 <title>Full Code Example</title> 3948 <para> 3949 <example> 3950 <title>Example of AC97 Interface</title> 3951 <programlisting> 3952<![CDATA[ 3953 struct mychip { 3954 .... 3955 struct snd_ac97 *ac97; 3956 .... 3957 }; 3958 3959 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97, 3960 unsigned short reg) 3961 { 3962 struct mychip *chip = ac97->private_data; 3963 .... 3964 /* read a register value here from the codec */ 3965 return the_register_value; 3966 } 3967 3968 static void snd_mychip_ac97_write(struct snd_ac97 *ac97, 3969 unsigned short reg, unsigned short val) 3970 { 3971 struct mychip *chip = ac97->private_data; 3972 .... 3973 /* write the given register value to the codec */ 3974 } 3975 3976 static int snd_mychip_ac97(struct mychip *chip) 3977 { 3978 struct snd_ac97_bus *bus; 3979 struct snd_ac97_template ac97; 3980 int err; 3981 static struct snd_ac97_bus_ops ops = { 3982 .write = snd_mychip_ac97_write, 3983 .read = snd_mychip_ac97_read, 3984 }; 3985 3986 err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus); 3987 if (err < 0) 3988 return err; 3989 memset(&ac97, 0, sizeof(ac97)); 3990 ac97.private_data = chip; 3991 return snd_ac97_mixer(bus, &ac97, &chip->ac97); 3992 } 3993 3994]]> 3995 </programlisting> 3996 </example> 3997 </para> 3998 </section> 3999 4000 <section id="api-ac97-constructor"> 4001 <title>Constructor</title> 4002 <para> 4003 To create an ac97 instance, first call <function>snd_ac97_bus</function> 4004 with an <type>ac97_bus_ops_t</type> record with callback functions. 4005 4006 <informalexample> 4007 <programlisting> 4008<![CDATA[ 4009 struct snd_ac97_bus *bus; 4010 static struct snd_ac97_bus_ops ops = { 4011 .write = snd_mychip_ac97_write, 4012 .read = snd_mychip_ac97_read, 4013 }; 4014 4015 snd_ac97_bus(card, 0, &ops, NULL, &pbus); 4016]]> 4017 </programlisting> 4018 </informalexample> 4019 4020 The bus record is shared among all belonging ac97 instances. 4021 </para> 4022 4023 <para> 4024 And then call <function>snd_ac97_mixer()</function> with an 4025 struct <structname>snd_ac97_template</structname> 4026 record together with the bus pointer created above. 4027 4028 <informalexample> 4029 <programlisting> 4030<![CDATA[ 4031 struct snd_ac97_template ac97; 4032 int err; 4033 4034 memset(&ac97, 0, sizeof(ac97)); 4035 ac97.private_data = chip; 4036 snd_ac97_mixer(bus, &ac97, &chip->ac97); 4037]]> 4038 </programlisting> 4039 </informalexample> 4040 4041 where chip->ac97 is a pointer to a newly created 4042 <type>ac97_t</type> instance. 4043 In this case, the chip pointer is set as the private data, so that 4044 the read/write callback functions can refer to this chip instance. 4045 This instance is not necessarily stored in the chip 4046 record. If you need to change the register values from the 4047 driver, or need the suspend/resume of ac97 codecs, keep this 4048 pointer to pass to the corresponding functions. 4049 </para> 4050 </section> 4051 4052 <section id="api-ac97-callbacks"> 4053 <title>Callbacks</title> 4054 <para> 4055 The standard callbacks are <structfield>read</structfield> and 4056 <structfield>write</structfield>. Obviously they 4057 correspond to the functions for read and write accesses to the 4058 hardware low-level codes. 4059 </para> 4060 4061 <para> 4062 The <structfield>read</structfield> callback returns the 4063 register value specified in the argument. 4064 4065 <informalexample> 4066 <programlisting> 4067<![CDATA[ 4068 static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97, 4069 unsigned short reg) 4070 { 4071 struct mychip *chip = ac97->private_data; 4072 .... 4073 return the_register_value; 4074 } 4075]]> 4076 </programlisting> 4077 </informalexample> 4078 4079 Here, the chip can be cast from ac97->private_data. 4080 </para> 4081 4082 <para> 4083 Meanwhile, the <structfield>write</structfield> callback is 4084 used to set the register value. 4085 4086 <informalexample> 4087 <programlisting> 4088<![CDATA[ 4089 static void snd_mychip_ac97_write(struct snd_ac97 *ac97, 4090 unsigned short reg, unsigned short val) 4091]]> 4092 </programlisting> 4093 </informalexample> 4094 </para> 4095 4096 <para> 4097 These callbacks are non-atomic like the control API callbacks. 4098 </para> 4099 4100 <para> 4101 There are also other callbacks: 4102 <structfield>reset</structfield>, 4103 <structfield>wait</structfield> and 4104 <structfield>init</structfield>. 4105 </para> 4106 4107 <para> 4108 The <structfield>reset</structfield> callback is used to reset 4109 the codec. If the chip requires a special kind of reset, you can 4110 define this callback. 4111 </para> 4112 4113 <para> 4114 The <structfield>wait</structfield> callback is used to 4115 add some waiting time in the standard initialization of the codec. If the 4116 chip requires the extra waiting time, define this callback. 4117 </para> 4118 4119 <para> 4120 The <structfield>init</structfield> callback is used for 4121 additional initialization of the codec. 4122 </para> 4123 </section> 4124 4125 <section id="api-ac97-updating-registers"> 4126 <title>Updating Registers in The Driver</title> 4127 <para> 4128 If you need to access to the codec from the driver, you can 4129 call the following functions: 4130 <function>snd_ac97_write()</function>, 4131 <function>snd_ac97_read()</function>, 4132 <function>snd_ac97_update()</function> and 4133 <function>snd_ac97_update_bits()</function>. 4134 </para> 4135 4136 <para> 4137 Both <function>snd_ac97_write()</function> and 4138 <function>snd_ac97_update()</function> functions are used to 4139 set a value to the given register 4140 (<constant>AC97_XXX</constant>). The difference between them is 4141 that <function>snd_ac97_update()</function> doesn't write a 4142 value if the given value has been already set, while 4143 <function>snd_ac97_write()</function> always rewrites the 4144 value. 4145 4146 <informalexample> 4147 <programlisting> 4148<![CDATA[ 4149 snd_ac97_write(ac97, AC97_MASTER, 0x8080); 4150 snd_ac97_update(ac97, AC97_MASTER, 0x8080); 4151]]> 4152 </programlisting> 4153 </informalexample> 4154 </para> 4155 4156 <para> 4157 <function>snd_ac97_read()</function> is used to read the value 4158 of the given register. For example, 4159 4160 <informalexample> 4161 <programlisting> 4162<![CDATA[ 4163 value = snd_ac97_read(ac97, AC97_MASTER); 4164]]> 4165 </programlisting> 4166 </informalexample> 4167 </para> 4168 4169 <para> 4170 <function>snd_ac97_update_bits()</function> is used to update 4171 some bits in the given register. 4172 4173 <informalexample> 4174 <programlisting> 4175<![CDATA[ 4176 snd_ac97_update_bits(ac97, reg, mask, value); 4177]]> 4178 </programlisting> 4179 </informalexample> 4180 </para> 4181 4182 <para> 4183 Also, there is a function to change the sample rate (of a 4184 given register such as 4185 <constant>AC97_PCM_FRONT_DAC_RATE</constant>) when VRA or 4186 DRA is supported by the codec: 4187 <function>snd_ac97_set_rate()</function>. 4188 4189 <informalexample> 4190 <programlisting> 4191<![CDATA[ 4192 snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100); 4193]]> 4194 </programlisting> 4195 </informalexample> 4196 </para> 4197 4198 <para> 4199 The following registers are available to set the rate: 4200 <constant>AC97_PCM_MIC_ADC_RATE</constant>, 4201 <constant>AC97_PCM_FRONT_DAC_RATE</constant>, 4202 <constant>AC97_PCM_LR_ADC_RATE</constant>, 4203 <constant>AC97_SPDIF</constant>. When 4204 <constant>AC97_SPDIF</constant> is specified, the register is 4205 not really changed but the corresponding IEC958 status bits will 4206 be updated. 4207 </para> 4208 </section> 4209 4210 <section id="api-ac97-clock-adjustment"> 4211 <title>Clock Adjustment</title> 4212 <para> 4213 In some chips, the clock of the codec isn't 48000 but using a 4214 PCI clock (to save a quartz!). In this case, change the field 4215 bus->clock to the corresponding 4216 value. For example, intel8x0 4217 and es1968 drivers have their own function to read from the clock. 4218 </para> 4219 </section> 4220 4221 <section id="api-ac97-proc-files"> 4222 <title>Proc Files</title> 4223 <para> 4224 The ALSA AC97 interface will create a proc file such as 4225 <filename>/proc/asound/card0/codec97#0/ac97#0-0</filename> and 4226 <filename>ac97#0-0+regs</filename>. You can refer to these files to 4227 see the current status and registers of the codec. 4228 </para> 4229 </section> 4230 4231 <section id="api-ac97-multiple-codecs"> 4232 <title>Multiple Codecs</title> 4233 <para> 4234 When there are several codecs on the same card, you need to 4235 call <function>snd_ac97_mixer()</function> multiple times with 4236 ac97.num=1 or greater. The <structfield>num</structfield> field 4237 specifies the codec number. 4238 </para> 4239 4240 <para> 4241 If you set up multiple codecs, you either need to write 4242 different callbacks for each codec or check 4243 ac97->num in the callback routines. 4244 </para> 4245 </section> 4246 4247 </chapter> 4248 4249 4250<!-- ****************************************************** --> 4251<!-- MIDI (MPU401-UART) Interface --> 4252<!-- ****************************************************** --> 4253 <chapter id="midi-interface"> 4254 <title>MIDI (MPU401-UART) Interface</title> 4255 4256 <section id="midi-interface-general"> 4257 <title>General</title> 4258 <para> 4259 Many soundcards have built-in MIDI (MPU401-UART) 4260 interfaces. When the soundcard supports the standard MPU401-UART 4261 interface, most likely you can use the ALSA MPU401-UART API. The 4262 MPU401-UART API is defined in 4263 <filename><sound/mpu401.h></filename>. 4264 </para> 4265 4266 <para> 4267 Some soundchips have a similar but slightly different 4268 implementation of mpu401 stuff. For example, emu10k1 has its own 4269 mpu401 routines. 4270 </para> 4271 </section> 4272 4273 <section id="midi-interface-constructor"> 4274 <title>Constructor</title> 4275 <para> 4276 To create a rawmidi object, call 4277 <function>snd_mpu401_uart_new()</function>. 4278 4279 <informalexample> 4280 <programlisting> 4281<![CDATA[ 4282 struct snd_rawmidi *rmidi; 4283 snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags, 4284 irq, &rmidi); 4285]]> 4286 </programlisting> 4287 </informalexample> 4288 </para> 4289 4290 <para> 4291 The first argument is the card pointer, and the second is the 4292 index of this component. You can create up to 8 rawmidi 4293 devices. 4294 </para> 4295 4296 <para> 4297 The third argument is the type of the hardware, 4298 <constant>MPU401_HW_XXX</constant>. If it's not a special one, 4299 you can use <constant>MPU401_HW_MPU401</constant>. 4300 </para> 4301 4302 <para> 4303 The 4th argument is the I/O port address. Many 4304 backward-compatible MPU401 have an I/O port such as 0x330. Or, it 4305 might be a part of its own PCI I/O region. It depends on the 4306 chip design. 4307 </para> 4308 4309 <para> 4310 The 5th argument is a bitflag for additional information. 4311 When the I/O port address above is part of the PCI I/O 4312 region, the MPU401 I/O port might have been already allocated 4313 (reserved) by the driver itself. In such a case, pass a bit flag 4314 <constant>MPU401_INFO_INTEGRATED</constant>, 4315 and the mpu401-uart layer will allocate the I/O ports by itself. 4316 </para> 4317 4318 <para> 4319 When the controller supports only the input or output MIDI stream, 4320 pass the <constant>MPU401_INFO_INPUT</constant> or 4321 <constant>MPU401_INFO_OUTPUT</constant> bitflag, respectively. 4322 Then the rawmidi instance is created as a single stream. 4323 </para> 4324 4325 <para> 4326 <constant>MPU401_INFO_MMIO</constant> bitflag is used to change 4327 the access method to MMIO (via readb and writeb) instead of 4328 iob and outb. In this case, you have to pass the iomapped address 4329 to <function>snd_mpu401_uart_new()</function>. 4330 </para> 4331 4332 <para> 4333 When <constant>MPU401_INFO_TX_IRQ</constant> is set, the output 4334 stream isn't checked in the default interrupt handler. The driver 4335 needs to call <function>snd_mpu401_uart_interrupt_tx()</function> 4336 by itself to start processing the output stream in the irq handler. 4337 </para> 4338 4339 <para> 4340 If the MPU-401 interface shares its interrupt with the other logical 4341 devices on the card, set <constant>MPU401_INFO_IRQ_HOOK</constant> 4342 (see <link linkend="midi-interface-interrupt-handler"><citetitle> 4343 below</citetitle></link>). 4344 </para> 4345 4346 <para> 4347 Usually, the port address corresponds to the command port and 4348 port + 1 corresponds to the data port. If not, you may change 4349 the <structfield>cport</structfield> field of 4350 struct <structname>snd_mpu401</structname> manually 4351 afterward. However, <structname>snd_mpu401</structname> pointer is not 4352 returned explicitly by 4353 <function>snd_mpu401_uart_new()</function>. You need to cast 4354 rmidi->private_data to 4355 <structname>snd_mpu401</structname> explicitly, 4356 4357 <informalexample> 4358 <programlisting> 4359<![CDATA[ 4360 struct snd_mpu401 *mpu; 4361 mpu = rmidi->private_data; 4362]]> 4363 </programlisting> 4364 </informalexample> 4365 4366 and reset the cport as you like: 4367 4368 <informalexample> 4369 <programlisting> 4370<![CDATA[ 4371 mpu->cport = my_own_control_port; 4372]]> 4373 </programlisting> 4374 </informalexample> 4375 </para> 4376 4377 <para> 4378 The 6th argument specifies the ISA irq number that will be 4379 allocated. If no interrupt is to be allocated (because your 4380 code is already allocating a shared interrupt, or because the 4381 device does not use interrupts), pass -1 instead. 4382 For a MPU-401 device without an interrupt, a polling timer 4383 will be used instead. 4384 </para> 4385 </section> 4386 4387 <section id="midi-interface-interrupt-handler"> 4388 <title>Interrupt Handler</title> 4389 <para> 4390 When the interrupt is allocated in 4391 <function>snd_mpu401_uart_new()</function>, an exclusive ISA 4392 interrupt handler is automatically used, hence you don't have 4393 anything else to do than creating the mpu401 stuff. Otherwise, you 4394 have to set <constant>MPU401_INFO_IRQ_HOOK</constant>, and call 4395 <function>snd_mpu401_uart_interrupt()</function> explicitly from your 4396 own interrupt handler when it has determined that a UART interrupt 4397 has occurred. 4398 </para> 4399 4400 <para> 4401 In this case, you need to pass the private_data of the 4402 returned rawmidi object from 4403 <function>snd_mpu401_uart_new()</function> as the second 4404 argument of <function>snd_mpu401_uart_interrupt()</function>. 4405 4406 <informalexample> 4407 <programlisting> 4408<![CDATA[ 4409 snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs); 4410]]> 4411 </programlisting> 4412 </informalexample> 4413 </para> 4414 </section> 4415 4416 </chapter> 4417 4418 4419<!-- ****************************************************** --> 4420<!-- RawMIDI Interface --> 4421<!-- ****************************************************** --> 4422 <chapter id="rawmidi-interface"> 4423 <title>RawMIDI Interface</title> 4424 4425 <section id="rawmidi-interface-overview"> 4426 <title>Overview</title> 4427 4428 <para> 4429 The raw MIDI interface is used for hardware MIDI ports that can 4430 be accessed as a byte stream. It is not used for synthesizer 4431 chips that do not directly understand MIDI. 4432 </para> 4433 4434 <para> 4435 ALSA handles file and buffer management. All you have to do is 4436 to write some code to move data between the buffer and the 4437 hardware. 4438 </para> 4439 4440 <para> 4441 The rawmidi API is defined in 4442 <filename><sound/rawmidi.h></filename>. 4443 </para> 4444 </section> 4445 4446 <section id="rawmidi-interface-constructor"> 4447 <title>Constructor</title> 4448 4449 <para> 4450 To create a rawmidi device, call the 4451 <function>snd_rawmidi_new</function> function: 4452 <informalexample> 4453 <programlisting> 4454<![CDATA[ 4455 struct snd_rawmidi *rmidi; 4456 err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi); 4457 if (err < 0) 4458 return err; 4459 rmidi->private_data = chip; 4460 strcpy(rmidi->name, "My MIDI"); 4461 rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT | 4462 SNDRV_RAWMIDI_INFO_INPUT | 4463 SNDRV_RAWMIDI_INFO_DUPLEX; 4464]]> 4465 </programlisting> 4466 </informalexample> 4467 </para> 4468 4469 <para> 4470 The first argument is the card pointer, the second argument is 4471 the ID string. 4472 </para> 4473 4474 <para> 4475 The third argument is the index of this component. You can 4476 create up to 8 rawmidi devices. 4477 </para> 4478 4479 <para> 4480 The fourth and fifth arguments are the number of output and 4481 input substreams, respectively, of this device (a substream is 4482 the equivalent of a MIDI port). 4483 </para> 4484 4485 <para> 4486 Set the <structfield>info_flags</structfield> field to specify 4487 the capabilities of the device. 4488 Set <constant>SNDRV_RAWMIDI_INFO_OUTPUT</constant> if there is 4489 at least one output port, 4490 <constant>SNDRV_RAWMIDI_INFO_INPUT</constant> if there is at 4491 least one input port, 4492 and <constant>SNDRV_RAWMIDI_INFO_DUPLEX</constant> if the device 4493 can handle output and input at the same time. 4494 </para> 4495 4496 <para> 4497 After the rawmidi device is created, you need to set the 4498 operators (callbacks) for each substream. There are helper 4499 functions to set the operators for all the substreams of a device: 4500 <informalexample> 4501 <programlisting> 4502<![CDATA[ 4503 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops); 4504 snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops); 4505]]> 4506 </programlisting> 4507 </informalexample> 4508 </para> 4509 4510 <para> 4511 The operators are usually defined like this: 4512 <informalexample> 4513 <programlisting> 4514<![CDATA[ 4515 static struct snd_rawmidi_ops snd_mymidi_output_ops = { 4516 .open = snd_mymidi_output_open, 4517 .close = snd_mymidi_output_close, 4518 .trigger = snd_mymidi_output_trigger, 4519 }; 4520]]> 4521 </programlisting> 4522 </informalexample> 4523 These callbacks are explained in the <link 4524 linkend="rawmidi-interface-callbacks"><citetitle>Callbacks</citetitle></link> 4525 section. 4526 </para> 4527 4528 <para> 4529 If there are more than one substream, you should give a 4530 unique name to each of them: 4531 <informalexample> 4532 <programlisting> 4533<![CDATA[ 4534 struct snd_rawmidi_substream *substream; 4535 list_for_each_entry(substream, 4536 &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams, 4537 list { 4538 sprintf(substream->name, "My MIDI Port %d", substream->number + 1); 4539 } 4540 /* same for SNDRV_RAWMIDI_STREAM_INPUT */ 4541]]> 4542 </programlisting> 4543 </informalexample> 4544 </para> 4545 </section> 4546 4547 <section id="rawmidi-interface-callbacks"> 4548 <title>Callbacks</title> 4549 4550 <para> 4551 In all the callbacks, the private data that you've set for the 4552 rawmidi device can be accessed as 4553 substream->rmidi->private_data. 4554 <!-- <code> isn't available before DocBook 4.3 --> 4555 </para> 4556 4557 <para> 4558 If there is more than one port, your callbacks can determine the 4559 port index from the struct snd_rawmidi_substream data passed to each 4560 callback: 4561 <informalexample> 4562 <programlisting> 4563<![CDATA[ 4564 struct snd_rawmidi_substream *substream; 4565 int index = substream->number; 4566]]> 4567 </programlisting> 4568 </informalexample> 4569 </para> 4570 4571 <section id="rawmidi-interface-op-open"> 4572 <title><function>open</function> callback</title> 4573 4574 <informalexample> 4575 <programlisting> 4576<![CDATA[ 4577 static int snd_xxx_open(struct snd_rawmidi_substream *substream); 4578]]> 4579 </programlisting> 4580 </informalexample> 4581 4582 <para> 4583 This is called when a substream is opened. 4584 You can initialize the hardware here, but you shouldn't 4585 start transmitting/receiving data yet. 4586 </para> 4587 </section> 4588 4589 <section id="rawmidi-interface-op-close"> 4590 <title><function>close</function> callback</title> 4591 4592 <informalexample> 4593 <programlisting> 4594<![CDATA[ 4595 static int snd_xxx_close(struct snd_rawmidi_substream *substream); 4596]]> 4597 </programlisting> 4598 </informalexample> 4599 4600 <para> 4601 Guess what. 4602 </para> 4603 4604 <para> 4605 The <function>open</function> and <function>close</function> 4606 callbacks of a rawmidi device are serialized with a mutex, 4607 and can sleep. 4608 </para> 4609 </section> 4610 4611 <section id="rawmidi-interface-op-trigger-out"> 4612 <title><function>trigger</function> callback for output 4613 substreams</title> 4614 4615 <informalexample> 4616 <programlisting> 4617<![CDATA[ 4618 static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up); 4619]]> 4620 </programlisting> 4621 </informalexample> 4622 4623 <para> 4624 This is called with a nonzero <parameter>up</parameter> 4625 parameter when there is some data in the substream buffer that 4626 must be transmitted. 4627 </para> 4628 4629 <para> 4630 To read data from the buffer, call 4631 <function>snd_rawmidi_transmit_peek</function>. It will 4632 return the number of bytes that have been read; this will be 4633 less than the number of bytes requested when there are no more 4634 data in the buffer. 4635 After the data have been transmitted successfully, call 4636 <function>snd_rawmidi_transmit_ack</function> to remove the 4637 data from the substream buffer: 4638 <informalexample> 4639 <programlisting> 4640<![CDATA[ 4641 unsigned char data; 4642 while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) { 4643 if (snd_mychip_try_to_transmit(data)) 4644 snd_rawmidi_transmit_ack(substream, 1); 4645 else 4646 break; /* hardware FIFO full */ 4647 } 4648]]> 4649 </programlisting> 4650 </informalexample> 4651 </para> 4652 4653 <para> 4654 If you know beforehand that the hardware will accept data, you 4655 can use the <function>snd_rawmidi_transmit</function> function 4656 which reads some data and removes them from the buffer at once: 4657 <informalexample> 4658 <programlisting> 4659<![CDATA[ 4660 while (snd_mychip_transmit_possible()) { 4661 unsigned char data; 4662 if (snd_rawmidi_transmit(substream, &data, 1) != 1) 4663 break; /* no more data */ 4664 snd_mychip_transmit(data); 4665 } 4666]]> 4667 </programlisting> 4668 </informalexample> 4669 </para> 4670 4671 <para> 4672 If you know beforehand how many bytes you can accept, you can 4673 use a buffer size greater than one with the 4674 <function>snd_rawmidi_transmit*</function> functions. 4675 </para> 4676 4677 <para> 4678 The <function>trigger</function> callback must not sleep. If 4679 the hardware FIFO is full before the substream buffer has been 4680 emptied, you have to continue transmitting data later, either 4681 in an interrupt handler, or with a timer if the hardware 4682 doesn't have a MIDI transmit interrupt. 4683 </para> 4684 4685 <para> 4686 The <function>trigger</function> callback is called with a 4687 zero <parameter>up</parameter> parameter when the transmission 4688 of data should be aborted. 4689 </para> 4690 </section> 4691 4692 <section id="rawmidi-interface-op-trigger-in"> 4693 <title><function>trigger</function> callback for input 4694 substreams</title> 4695 4696 <informalexample> 4697 <programlisting> 4698<![CDATA[ 4699 static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up); 4700]]> 4701 </programlisting> 4702 </informalexample> 4703 4704 <para> 4705 This is called with a nonzero <parameter>up</parameter> 4706 parameter to enable receiving data, or with a zero 4707 <parameter>up</parameter> parameter do disable receiving data. 4708 </para> 4709 4710 <para> 4711 The <function>trigger</function> callback must not sleep; the 4712 actual reading of data from the device is usually done in an 4713 interrupt handler. 4714 </para> 4715 4716 <para> 4717 When data reception is enabled, your interrupt handler should 4718 call <function>snd_rawmidi_receive</function> for all received 4719 data: 4720 <informalexample> 4721 <programlisting> 4722<![CDATA[ 4723 void snd_mychip_midi_interrupt(...) 4724 { 4725 while (mychip_midi_available()) { 4726 unsigned char data; 4727 data = mychip_midi_read(); 4728 snd_rawmidi_receive(substream, &data, 1); 4729 } 4730 } 4731]]> 4732 </programlisting> 4733 </informalexample> 4734 </para> 4735 </section> 4736 4737 <section id="rawmidi-interface-op-drain"> 4738 <title><function>drain</function> callback</title> 4739 4740 <informalexample> 4741 <programlisting> 4742<![CDATA[ 4743 static void snd_xxx_drain(struct snd_rawmidi_substream *substream); 4744]]> 4745 </programlisting> 4746 </informalexample> 4747 4748 <para> 4749 This is only used with output substreams. This function should wait 4750 until all data read from the substream buffer have been transmitted. 4751 This ensures that the device can be closed and the driver unloaded 4752 without losing data. 4753 </para> 4754 4755 <para> 4756 This callback is optional. If you do not set 4757 <structfield>drain</structfield> in the struct snd_rawmidi_ops 4758 structure, ALSA will simply wait for 50 milliseconds 4759 instead. 4760 </para> 4761 </section> 4762 </section> 4763 4764 </chapter> 4765 4766 4767<!-- ****************************************************** --> 4768<!-- Miscellaneous Devices --> 4769<!-- ****************************************************** --> 4770 <chapter id="misc-devices"> 4771 <title>Miscellaneous Devices</title> 4772 4773 <section id="misc-devices-opl3"> 4774 <title>FM OPL3</title> 4775 <para> 4776 The FM OPL3 is still used in many chips (mainly for backward 4777 compatibility). ALSA has a nice OPL3 FM control layer, too. The 4778 OPL3 API is defined in 4779 <filename><sound/opl3.h></filename>. 4780 </para> 4781 4782 <para> 4783 FM registers can be directly accessed through the direct-FM API, 4784 defined in <filename><sound/asound_fm.h></filename>. In 4785 ALSA native mode, FM registers are accessed through 4786 the Hardware-Dependent Device direct-FM extension API, whereas in 4787 OSS compatible mode, FM registers can be accessed with the OSS 4788 direct-FM compatible API in <filename>/dev/dmfmX</filename> device. 4789 </para> 4790 4791 <para> 4792 To create the OPL3 component, you have two functions to 4793 call. The first one is a constructor for the <type>opl3_t</type> 4794 instance. 4795 4796 <informalexample> 4797 <programlisting> 4798<![CDATA[ 4799 struct snd_opl3 *opl3; 4800 snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX, 4801 integrated, &opl3); 4802]]> 4803 </programlisting> 4804 </informalexample> 4805 </para> 4806 4807 <para> 4808 The first argument is the card pointer, the second one is the 4809 left port address, and the third is the right port address. In 4810 most cases, the right port is placed at the left port + 2. 4811 </para> 4812 4813 <para> 4814 The fourth argument is the hardware type. 4815 </para> 4816 4817 <para> 4818 When the left and right ports have been already allocated by 4819 the card driver, pass non-zero to the fifth argument 4820 (<parameter>integrated</parameter>). Otherwise, the opl3 module will 4821 allocate the specified ports by itself. 4822 </para> 4823 4824 <para> 4825 When the accessing the hardware requires special method 4826 instead of the standard I/O access, you can create opl3 instance 4827 separately with <function>snd_opl3_new()</function>. 4828 4829 <informalexample> 4830 <programlisting> 4831<![CDATA[ 4832 struct snd_opl3 *opl3; 4833 snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3); 4834]]> 4835 </programlisting> 4836 </informalexample> 4837 </para> 4838 4839 <para> 4840 Then set <structfield>command</structfield>, 4841 <structfield>private_data</structfield> and 4842 <structfield>private_free</structfield> for the private 4843 access function, the private data and the destructor. 4844 The l_port and r_port are not necessarily set. Only the 4845 command must be set properly. You can retrieve the data 4846 from the opl3->private_data field. 4847 </para> 4848 4849 <para> 4850 After creating the opl3 instance via <function>snd_opl3_new()</function>, 4851 call <function>snd_opl3_init()</function> to initialize the chip to the 4852 proper state. Note that <function>snd_opl3_create()</function> always 4853 calls it internally. 4854 </para> 4855 4856 <para> 4857 If the opl3 instance is created successfully, then create a 4858 hwdep device for this opl3. 4859 4860 <informalexample> 4861 <programlisting> 4862<![CDATA[ 4863 struct snd_hwdep *opl3hwdep; 4864 snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep); 4865]]> 4866 </programlisting> 4867 </informalexample> 4868 </para> 4869 4870 <para> 4871 The first argument is the <type>opl3_t</type> instance you 4872 created, and the second is the index number, usually 0. 4873 </para> 4874 4875 <para> 4876 The third argument is the index-offset for the sequencer 4877 client assigned to the OPL3 port. When there is an MPU401-UART, 4878 give 1 for here (UART always takes 0). 4879 </para> 4880 </section> 4881 4882 <section id="misc-devices-hardware-dependent"> 4883 <title>Hardware-Dependent Devices</title> 4884 <para> 4885 Some chips need user-space access for special 4886 controls or for loading the micro code. In such a case, you can 4887 create a hwdep (hardware-dependent) device. The hwdep API is 4888 defined in <filename><sound/hwdep.h></filename>. You can 4889 find examples in opl3 driver or 4890 <filename>isa/sb/sb16_csp.c</filename>. 4891 </para> 4892 4893 <para> 4894 The creation of the <type>hwdep</type> instance is done via 4895 <function>snd_hwdep_new()</function>. 4896 4897 <informalexample> 4898 <programlisting> 4899<![CDATA[ 4900 struct snd_hwdep *hw; 4901 snd_hwdep_new(card, "My HWDEP", 0, &hw); 4902]]> 4903 </programlisting> 4904 </informalexample> 4905 4906 where the third argument is the index number. 4907 </para> 4908 4909 <para> 4910 You can then pass any pointer value to the 4911 <parameter>private_data</parameter>. 4912 If you assign a private data, you should define the 4913 destructor, too. The destructor function is set in 4914 the <structfield>private_free</structfield> field. 4915 4916 <informalexample> 4917 <programlisting> 4918<![CDATA[ 4919 struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL); 4920 hw->private_data = p; 4921 hw->private_free = mydata_free; 4922]]> 4923 </programlisting> 4924 </informalexample> 4925 4926 and the implementation of the destructor would be: 4927 4928 <informalexample> 4929 <programlisting> 4930<![CDATA[ 4931 static void mydata_free(struct snd_hwdep *hw) 4932 { 4933 struct mydata *p = hw->private_data; 4934 kfree(p); 4935 } 4936]]> 4937 </programlisting> 4938 </informalexample> 4939 </para> 4940 4941 <para> 4942 The arbitrary file operations can be defined for this 4943 instance. The file operators are defined in 4944 the <parameter>ops</parameter> table. For example, assume that 4945 this chip needs an ioctl. 4946 4947 <informalexample> 4948 <programlisting> 4949<![CDATA[ 4950 hw->ops.open = mydata_open; 4951 hw->ops.ioctl = mydata_ioctl; 4952 hw->ops.release = mydata_release; 4953]]> 4954 </programlisting> 4955 </informalexample> 4956 4957 And implement the callback functions as you like. 4958 </para> 4959 </section> 4960 4961 <section id="misc-devices-IEC958"> 4962 <title>IEC958 (S/PDIF)</title> 4963 <para> 4964 Usually the controls for IEC958 devices are implemented via 4965 the control interface. There is a macro to compose a name string for 4966 IEC958 controls, <function>SNDRV_CTL_NAME_IEC958()</function> 4967 defined in <filename><include/asound.h></filename>. 4968 </para> 4969 4970 <para> 4971 There are some standard controls for IEC958 status bits. These 4972 controls use the type <type>SNDRV_CTL_ELEM_TYPE_IEC958</type>, 4973 and the size of element is fixed as 4 bytes array 4974 (value.iec958.status[x]). For the <structfield>info</structfield> 4975 callback, you don't specify 4976 the value field for this type (the count field must be set, 4977 though). 4978 </para> 4979 4980 <para> 4981 <quote>IEC958 Playback Con Mask</quote> is used to return the 4982 bit-mask for the IEC958 status bits of consumer mode. Similarly, 4983 <quote>IEC958 Playback Pro Mask</quote> returns the bitmask for 4984 professional mode. They are read-only controls, and are defined 4985 as MIXER controls (iface = 4986 <constant>SNDRV_CTL_ELEM_IFACE_MIXER</constant>). 4987 </para> 4988 4989 <para> 4990 Meanwhile, <quote>IEC958 Playback Default</quote> control is 4991 defined for getting and setting the current default IEC958 4992 bits. Note that this one is usually defined as a PCM control 4993 (iface = <constant>SNDRV_CTL_ELEM_IFACE_PCM</constant>), 4994 although in some places it's defined as a MIXER control. 4995 </para> 4996 4997 <para> 4998 In addition, you can define the control switches to 4999 enable/disable or to set the raw bit mode. The implementation 5000 will depend on the chip, but the control should be named as 5001 <quote>IEC958 xxx</quote>, preferably using 5002 the <function>SNDRV_CTL_NAME_IEC958()</function> macro. 5003 </para> 5004 5005 <para> 5006 You can find several cases, for example, 5007 <filename>pci/emu10k1</filename>, 5008 <filename>pci/ice1712</filename>, or 5009 <filename>pci/cmipci.c</filename>. 5010 </para> 5011 </section> 5012 5013 </chapter> 5014 5015 5016<!-- ****************************************************** --> 5017<!-- Buffer and Memory Management --> 5018<!-- ****************************************************** --> 5019 <chapter id="buffer-and-memory"> 5020 <title>Buffer and Memory Management</title> 5021 5022 <section id="buffer-and-memory-buffer-types"> 5023 <title>Buffer Types</title> 5024 <para> 5025 ALSA provides several different buffer allocation functions 5026 depending on the bus and the architecture. All these have a 5027 consistent API. The allocation of physically-contiguous pages is 5028 done via 5029 <function>snd_malloc_xxx_pages()</function> function, where xxx 5030 is the bus type. 5031 </para> 5032 5033 <para> 5034 The allocation of pages with fallback is 5035 <function>snd_malloc_xxx_pages_fallback()</function>. This 5036 function tries to allocate the specified pages but if the pages 5037 are not available, it tries to reduce the page sizes until 5038 enough space is found. 5039 </para> 5040 5041 <para> 5042 The release the pages, call 5043 <function>snd_free_xxx_pages()</function> function. 5044 </para> 5045 5046 <para> 5047 Usually, ALSA drivers try to allocate and reserve 5048 a large contiguous physical space 5049 at the time the module is loaded for the later use. 5050 This is called <quote>pre-allocation</quote>. 5051 As already written, you can call the following function at 5052 pcm instance construction time (in the case of PCI bus). 5053 5054 <informalexample> 5055 <programlisting> 5056<![CDATA[ 5057 snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV, 5058 snd_dma_pci_data(pci), size, max); 5059]]> 5060 </programlisting> 5061 </informalexample> 5062 5063 where <parameter>size</parameter> is the byte size to be 5064 pre-allocated and the <parameter>max</parameter> is the maximum 5065 size to be changed via the <filename>prealloc</filename> proc file. 5066 The allocator will try to get an area as large as possible 5067 within the given size. 5068 </para> 5069 5070 <para> 5071 The second argument (type) and the third argument (device pointer) 5072 are dependent on the bus. 5073 In the case of the ISA bus, pass <function>snd_dma_isa_data()</function> 5074 as the third argument with <constant>SNDRV_DMA_TYPE_DEV</constant> type. 5075 For the continuous buffer unrelated to the bus can be pre-allocated 5076 with <constant>SNDRV_DMA_TYPE_CONTINUOUS</constant> type and the 5077 <function>snd_dma_continuous_data(GFP_KERNEL)</function> device pointer, 5078 where <constant>GFP_KERNEL</constant> is the kernel allocation flag to 5079 use. 5080 For the PCI scatter-gather buffers, use 5081 <constant>SNDRV_DMA_TYPE_DEV_SG</constant> with 5082 <function>snd_dma_pci_data(pci)</function> 5083 (see the 5084 <link linkend="buffer-and-memory-non-contiguous"><citetitle>Non-Contiguous Buffers 5085 </citetitle></link> section). 5086 </para> 5087 5088 <para> 5089 Once the buffer is pre-allocated, you can use the 5090 allocator in the <structfield>hw_params</structfield> callback: 5091 5092 <informalexample> 5093 <programlisting> 5094<![CDATA[ 5095 snd_pcm_lib_malloc_pages(substream, size); 5096]]> 5097 </programlisting> 5098 </informalexample> 5099 5100 Note that you have to pre-allocate to use this function. 5101 </para> 5102 </section> 5103 5104 <section id="buffer-and-memory-external-hardware"> 5105 <title>External Hardware Buffers</title> 5106 <para> 5107 Some chips have their own hardware buffers and the DMA 5108 transfer from the host memory is not available. In such a case, 5109 you need to either 1) copy/set the audio data directly to the 5110 external hardware buffer, or 2) make an intermediate buffer and 5111 copy/set the data from it to the external hardware buffer in 5112 interrupts (or in tasklets, preferably). 5113 </para> 5114 5115 <para> 5116 The first case works fine if the external hardware buffer is large 5117 enough. This method doesn't need any extra buffers and thus is 5118 more effective. You need to define the 5119 <structfield>copy</structfield> and 5120 <structfield>silence</structfield> callbacks for 5121 the data transfer. However, there is a drawback: it cannot 5122 be mmapped. The examples are GUS's GF1 PCM or emu8000's 5123 wavetable PCM. 5124 </para> 5125 5126 <para> 5127 The second case allows for mmap on the buffer, although you have 5128 to handle an interrupt or a tasklet to transfer the data 5129 from the intermediate buffer to the hardware buffer. You can find an 5130 example in the vxpocket driver. 5131 </para> 5132 5133 <para> 5134 Another case is when the chip uses a PCI memory-map 5135 region for the buffer instead of the host memory. In this case, 5136 mmap is available only on certain architectures like the Intel one. 5137 In non-mmap mode, the data cannot be transferred as in the normal 5138 way. Thus you need to define the <structfield>copy</structfield> and 5139 <structfield>silence</structfield> callbacks as well, 5140 as in the cases above. The examples are found in 5141 <filename>rme32.c</filename> and <filename>rme96.c</filename>. 5142 </para> 5143 5144 <para> 5145 The implementation of the <structfield>copy</structfield> and 5146 <structfield>silence</structfield> callbacks depends upon 5147 whether the hardware supports interleaved or non-interleaved 5148 samples. The <structfield>copy</structfield> callback is 5149 defined like below, a bit 5150 differently depending whether the direction is playback or 5151 capture: 5152 5153 <informalexample> 5154 <programlisting> 5155<![CDATA[ 5156 static int playback_copy(struct snd_pcm_substream *substream, int channel, 5157 snd_pcm_uframes_t pos, void *src, snd_pcm_uframes_t count); 5158 static int capture_copy(struct snd_pcm_substream *substream, int channel, 5159 snd_pcm_uframes_t pos, void *dst, snd_pcm_uframes_t count); 5160]]> 5161 </programlisting> 5162 </informalexample> 5163 </para> 5164 5165 <para> 5166 In the case of interleaved samples, the second argument 5167 (<parameter>channel</parameter>) is not used. The third argument 5168 (<parameter>pos</parameter>) points the 5169 current position offset in frames. 5170 </para> 5171 5172 <para> 5173 The meaning of the fourth argument is different between 5174 playback and capture. For playback, it holds the source data 5175 pointer, and for capture, it's the destination data pointer. 5176 </para> 5177 5178 <para> 5179 The last argument is the number of frames to be copied. 5180 </para> 5181 5182 <para> 5183 What you have to do in this callback is again different 5184 between playback and capture directions. In the 5185 playback case, you copy the given amount of data 5186 (<parameter>count</parameter>) at the specified pointer 5187 (<parameter>src</parameter>) to the specified offset 5188 (<parameter>pos</parameter>) on the hardware buffer. When 5189 coded like memcpy-like way, the copy would be like: 5190 5191 <informalexample> 5192 <programlisting> 5193<![CDATA[ 5194 my_memcpy(my_buffer + frames_to_bytes(runtime, pos), src, 5195 frames_to_bytes(runtime, count)); 5196]]> 5197 </programlisting> 5198 </informalexample> 5199 </para> 5200 5201 <para> 5202 For the capture direction, you copy the given amount of 5203 data (<parameter>count</parameter>) at the specified offset 5204 (<parameter>pos</parameter>) on the hardware buffer to the 5205 specified pointer (<parameter>dst</parameter>). 5206 5207 <informalexample> 5208 <programlisting> 5209<![CDATA[ 5210 my_memcpy(dst, my_buffer + frames_to_bytes(runtime, pos), 5211 frames_to_bytes(runtime, count)); 5212]]> 5213 </programlisting> 5214 </informalexample> 5215 5216 Note that both the position and the amount of data are given 5217 in frames. 5218 </para> 5219 5220 <para> 5221 In the case of non-interleaved samples, the implementation 5222 will be a bit more complicated. 5223 </para> 5224 5225 <para> 5226 You need to check the channel argument, and if it's -1, copy 5227 the whole channels. Otherwise, you have to copy only the 5228 specified channel. Please check 5229 <filename>isa/gus/gus_pcm.c</filename> as an example. 5230 </para> 5231 5232 <para> 5233 The <structfield>silence</structfield> callback is also 5234 implemented in a similar way. 5235 5236 <informalexample> 5237 <programlisting> 5238<![CDATA[ 5239 static int silence(struct snd_pcm_substream *substream, int channel, 5240 snd_pcm_uframes_t pos, snd_pcm_uframes_t count); 5241]]> 5242 </programlisting> 5243 </informalexample> 5244 </para> 5245 5246 <para> 5247 The meanings of arguments are the same as in the 5248 <structfield>copy</structfield> 5249 callback, although there is no <parameter>src/dst</parameter> 5250 argument. In the case of interleaved samples, the channel 5251 argument has no meaning, as well as on 5252 <structfield>copy</structfield> callback. 5253 </para> 5254 5255 <para> 5256 The role of <structfield>silence</structfield> callback is to 5257 set the given amount 5258 (<parameter>count</parameter>) of silence data at the 5259 specified offset (<parameter>pos</parameter>) on the hardware 5260 buffer. Suppose that the data format is signed (that is, the 5261 silent-data is 0), and the implementation using a memset-like 5262 function would be like: 5263 5264 <informalexample> 5265 <programlisting> 5266<![CDATA[ 5267 my_memcpy(my_buffer + frames_to_bytes(runtime, pos), 0, 5268 frames_to_bytes(runtime, count)); 5269]]> 5270 </programlisting> 5271 </informalexample> 5272 </para> 5273 5274 <para> 5275 In the case of non-interleaved samples, again, the 5276 implementation becomes a bit more complicated. See, for example, 5277 <filename>isa/gus/gus_pcm.c</filename>. 5278 </para> 5279 </section> 5280 5281 <section id="buffer-and-memory-non-contiguous"> 5282 <title>Non-Contiguous Buffers</title> 5283 <para> 5284 If your hardware supports the page table as in emu10k1 or the 5285 buffer descriptors as in via82xx, you can use the scatter-gather 5286 (SG) DMA. ALSA provides an interface for handling SG-buffers. 5287 The API is provided in <filename><sound/pcm.h></filename>. 5288 </para> 5289 5290 <para> 5291 For creating the SG-buffer handler, call 5292 <function>snd_pcm_lib_preallocate_pages()</function> or 5293 <function>snd_pcm_lib_preallocate_pages_for_all()</function> 5294 with <constant>SNDRV_DMA_TYPE_DEV_SG</constant> 5295 in the PCM constructor like other PCI pre-allocator. 5296 You need to pass <function>snd_dma_pci_data(pci)</function>, 5297 where pci is the struct <structname>pci_dev</structname> pointer 5298 of the chip as well. 5299 The <type>struct snd_sg_buf</type> instance is created as 5300 substream->dma_private. You can cast 5301 the pointer like: 5302 5303 <informalexample> 5304 <programlisting> 5305<![CDATA[ 5306 struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private; 5307]]> 5308 </programlisting> 5309 </informalexample> 5310 </para> 5311 5312 <para> 5313 Then call <function>snd_pcm_lib_malloc_pages()</function> 5314 in the <structfield>hw_params</structfield> callback 5315 as well as in the case of normal PCI buffer. 5316 The SG-buffer handler will allocate the non-contiguous kernel 5317 pages of the given size and map them onto the virtually contiguous 5318 memory. The virtual pointer is addressed in runtime->dma_area. 5319 The physical address (runtime->dma_addr) is set to zero, 5320 because the buffer is physically non-contiguous. 5321 The physical address table is set up in sgbuf->table. 5322 You can get the physical address at a certain offset via 5323 <function>snd_pcm_sgbuf_get_addr()</function>. 5324 </para> 5325 5326 <para> 5327 When a SG-handler is used, you need to set 5328 <function>snd_pcm_sgbuf_ops_page</function> as 5329 the <structfield>page</structfield> callback. 5330 (See <link linkend="pcm-interface-operators-page-callback"> 5331 <citetitle>page callback section</citetitle></link>.) 5332 </para> 5333 5334 <para> 5335 To release the data, call 5336 <function>snd_pcm_lib_free_pages()</function> in the 5337 <structfield>hw_free</structfield> callback as usual. 5338 </para> 5339 </section> 5340 5341 <section id="buffer-and-memory-vmalloced"> 5342 <title>Vmalloc'ed Buffers</title> 5343 <para> 5344 It's possible to use a buffer allocated via 5345 <function>vmalloc</function>, for example, for an intermediate 5346 buffer. Since the allocated pages are not contiguous, you need 5347 to set the <structfield>page</structfield> callback to obtain 5348 the physical address at every offset. 5349 </para> 5350 5351 <para> 5352 The implementation of <structfield>page</structfield> callback 5353 would be like this: 5354 5355 <informalexample> 5356 <programlisting> 5357<![CDATA[ 5358 #include <linux/vmalloc.h> 5359 5360 /* get the physical page pointer on the given offset */ 5361 static struct page *mychip_page(struct snd_pcm_substream *substream, 5362 unsigned long offset) 5363 { 5364 void *pageptr = substream->runtime->dma_area + offset; 5365 return vmalloc_to_page(pageptr); 5366 } 5367]]> 5368 </programlisting> 5369 </informalexample> 5370 </para> 5371 </section> 5372 5373 </chapter> 5374 5375 5376<!-- ****************************************************** --> 5377<!-- Proc Interface --> 5378<!-- ****************************************************** --> 5379 <chapter id="proc-interface"> 5380 <title>Proc Interface</title> 5381 <para> 5382 ALSA provides an easy interface for procfs. The proc files are 5383 very useful for debugging. I recommend you set up proc files if 5384 you write a driver and want to get a running status or register 5385 dumps. The API is found in 5386 <filename><sound/info.h></filename>. 5387 </para> 5388 5389 <para> 5390 To create a proc file, call 5391 <function>snd_card_proc_new()</function>. 5392 5393 <informalexample> 5394 <programlisting> 5395<![CDATA[ 5396 struct snd_info_entry *entry; 5397 int err = snd_card_proc_new(card, "my-file", &entry); 5398]]> 5399 </programlisting> 5400 </informalexample> 5401 5402 where the second argument specifies the name of the proc file to be 5403 created. The above example will create a file 5404 <filename>my-file</filename> under the card directory, 5405 e.g. <filename>/proc/asound/card0/my-file</filename>. 5406 </para> 5407 5408 <para> 5409 Like other components, the proc entry created via 5410 <function>snd_card_proc_new()</function> will be registered and 5411 released automatically in the card registration and release 5412 functions. 5413 </para> 5414 5415 <para> 5416 When the creation is successful, the function stores a new 5417 instance in the pointer given in the third argument. 5418 It is initialized as a text proc file for read only. To use 5419 this proc file as a read-only text file as it is, set the read 5420 callback with a private data via 5421 <function>snd_info_set_text_ops()</function>. 5422 5423 <informalexample> 5424 <programlisting> 5425<![CDATA[ 5426 snd_info_set_text_ops(entry, chip, my_proc_read); 5427]]> 5428 </programlisting> 5429 </informalexample> 5430 5431 where the second argument (<parameter>chip</parameter>) is the 5432 private data to be used in the callbacks. The third parameter 5433 specifies the read buffer size and the fourth 5434 (<parameter>my_proc_read</parameter>) is the callback function, which 5435 is defined like 5436 5437 <informalexample> 5438 <programlisting> 5439<![CDATA[ 5440 static void my_proc_read(struct snd_info_entry *entry, 5441 struct snd_info_buffer *buffer); 5442]]> 5443 </programlisting> 5444 </informalexample> 5445 5446 </para> 5447 5448 <para> 5449 In the read callback, use <function>snd_iprintf()</function> for 5450 output strings, which works just like normal 5451 <function>printf()</function>. For example, 5452 5453 <informalexample> 5454 <programlisting> 5455<![CDATA[ 5456 static void my_proc_read(struct snd_info_entry *entry, 5457 struct snd_info_buffer *buffer) 5458 { 5459 struct my_chip *chip = entry->private_data; 5460 5461 snd_iprintf(buffer, "This is my chip!\n"); 5462 snd_iprintf(buffer, "Port = %ld\n", chip->port); 5463 } 5464]]> 5465 </programlisting> 5466 </informalexample> 5467 </para> 5468 5469 <para> 5470 The file permissions can be changed afterwards. As default, it's 5471 set as read only for all users. If you want to add write 5472 permission for the user (root as default), do as follows: 5473 5474 <informalexample> 5475 <programlisting> 5476<![CDATA[ 5477 entry->mode = S_IFREG | S_IRUGO | S_IWUSR; 5478]]> 5479 </programlisting> 5480 </informalexample> 5481 5482 and set the write buffer size and the callback 5483 5484 <informalexample> 5485 <programlisting> 5486<![CDATA[ 5487 entry->c.text.write = my_proc_write; 5488]]> 5489 </programlisting> 5490 </informalexample> 5491 </para> 5492 5493 <para> 5494 For the write callback, you can use 5495 <function>snd_info_get_line()</function> to get a text line, and 5496 <function>snd_info_get_str()</function> to retrieve a string from 5497 the line. Some examples are found in 5498 <filename>core/oss/mixer_oss.c</filename>, core/oss/and 5499 <filename>pcm_oss.c</filename>. 5500 </para> 5501 5502 <para> 5503 For a raw-data proc-file, set the attributes as follows: 5504 5505 <informalexample> 5506 <programlisting> 5507<![CDATA[ 5508 static struct snd_info_entry_ops my_file_io_ops = { 5509 .read = my_file_io_read, 5510 }; 5511 5512 entry->content = SNDRV_INFO_CONTENT_DATA; 5513 entry->private_data = chip; 5514 entry->c.ops = &my_file_io_ops; 5515 entry->size = 4096; 5516 entry->mode = S_IFREG | S_IRUGO; 5517]]> 5518 </programlisting> 5519 </informalexample> 5520 5521 For the raw data, <structfield>size</structfield> field must be 5522 set properly. This specifies the maximum size of the proc file access. 5523 </para> 5524 5525 <para> 5526 The read/write callbacks of raw mode are more direct than the text mode. 5527 You need to use a low-level I/O functions such as 5528 <function>copy_from/to_user()</function> to transfer the 5529 data. 5530 5531 <informalexample> 5532 <programlisting> 5533<![CDATA[ 5534 static ssize_t my_file_io_read(struct snd_info_entry *entry, 5535 void *file_private_data, 5536 struct file *file, 5537 char *buf, 5538 size_t count, 5539 loff_t pos) 5540 { 5541 if (copy_to_user(buf, local_data + pos, count)) 5542 return -EFAULT; 5543 return count; 5544 } 5545]]> 5546 </programlisting> 5547 </informalexample> 5548 5549 If the size of the info entry has been set up properly, 5550 <structfield>count</structfield> and <structfield>pos</structfield> are 5551 guaranteed to fit within 0 and the given size. 5552 You don't have to check the range in the callbacks unless any 5553 other condition is required. 5554 5555 </para> 5556 5557 </chapter> 5558 5559 5560<!-- ****************************************************** --> 5561<!-- Power Management --> 5562<!-- ****************************************************** --> 5563 <chapter id="power-management"> 5564 <title>Power Management</title> 5565 <para> 5566 If the chip is supposed to work with suspend/resume 5567 functions, you need to add power-management code to the 5568 driver. The additional code for power-management should be 5569 <function>ifdef</function>'ed with 5570 <constant>CONFIG_PM</constant>. 5571 </para> 5572 5573 <para> 5574 If the driver <emphasis>fully</emphasis> supports suspend/resume 5575 that is, the device can be 5576 properly resumed to its state when suspend was called, 5577 you can set the <constant>SNDRV_PCM_INFO_RESUME</constant> flag 5578 in the pcm info field. Usually, this is possible when the 5579 registers of the chip can be safely saved and restored to 5580 RAM. If this is set, the trigger callback is called with 5581 <constant>SNDRV_PCM_TRIGGER_RESUME</constant> after the resume 5582 callback completes. 5583 </para> 5584 5585 <para> 5586 Even if the driver doesn't support PM fully but 5587 partial suspend/resume is still possible, it's still worthy to 5588 implement suspend/resume callbacks. In such a case, applications 5589 would reset the status by calling 5590 <function>snd_pcm_prepare()</function> and restart the stream 5591 appropriately. Hence, you can define suspend/resume callbacks 5592 below but don't set <constant>SNDRV_PCM_INFO_RESUME</constant> 5593 info flag to the PCM. 5594 </para> 5595 5596 <para> 5597 Note that the trigger with SUSPEND can always be called when 5598 <function>snd_pcm_suspend_all</function> is called, 5599 regardless of the <constant>SNDRV_PCM_INFO_RESUME</constant> flag. 5600 The <constant>RESUME</constant> flag affects only the behavior 5601 of <function>snd_pcm_resume()</function>. 5602 (Thus, in theory, 5603 <constant>SNDRV_PCM_TRIGGER_RESUME</constant> isn't needed 5604 to be handled in the trigger callback when no 5605 <constant>SNDRV_PCM_INFO_RESUME</constant> flag is set. But, 5606 it's better to keep it for compatibility reasons.) 5607 </para> 5608 <para> 5609 In the earlier version of ALSA drivers, a common 5610 power-management layer was provided, but it has been removed. 5611 The driver needs to define the suspend/resume hooks according to 5612 the bus the device is connected to. In the case of PCI drivers, the 5613 callbacks look like below: 5614 5615 <informalexample> 5616 <programlisting> 5617<![CDATA[ 5618 #ifdef CONFIG_PM 5619 static int snd_my_suspend(struct pci_dev *pci, pm_message_t state) 5620 { 5621 .... /* do things for suspend */ 5622 return 0; 5623 } 5624 static int snd_my_resume(struct pci_dev *pci) 5625 { 5626 .... /* do things for suspend */ 5627 return 0; 5628 } 5629 #endif 5630]]> 5631 </programlisting> 5632 </informalexample> 5633 </para> 5634 5635 <para> 5636 The scheme of the real suspend job is as follows. 5637 5638 <orderedlist> 5639 <listitem><para>Retrieve the card and the chip data.</para></listitem> 5640 <listitem><para>Call <function>snd_power_change_state()</function> with 5641 <constant>SNDRV_CTL_POWER_D3hot</constant> to change the 5642 power status.</para></listitem> 5643 <listitem><para>Call <function>snd_pcm_suspend_all()</function> to suspend the running PCM streams.</para></listitem> 5644 <listitem><para>If AC97 codecs are used, call 5645 <function>snd_ac97_suspend()</function> for each codec.</para></listitem> 5646 <listitem><para>Save the register values if necessary.</para></listitem> 5647 <listitem><para>Stop the hardware if necessary.</para></listitem> 5648 <listitem><para>Disable the PCI device by calling 5649 <function>pci_disable_device()</function>. Then, call 5650 <function>pci_save_state()</function> at last.</para></listitem> 5651 </orderedlist> 5652 </para> 5653 5654 <para> 5655 A typical code would be like: 5656 5657 <informalexample> 5658 <programlisting> 5659<![CDATA[ 5660 static int mychip_suspend(struct pci_dev *pci, pm_message_t state) 5661 { 5662 /* (1) */ 5663 struct snd_card *card = pci_get_drvdata(pci); 5664 struct mychip *chip = card->private_data; 5665 /* (2) */ 5666 snd_power_change_state(card, SNDRV_CTL_POWER_D3hot); 5667 /* (3) */ 5668 snd_pcm_suspend_all(chip->pcm); 5669 /* (4) */ 5670 snd_ac97_suspend(chip->ac97); 5671 /* (5) */ 5672 snd_mychip_save_registers(chip); 5673 /* (6) */ 5674 snd_mychip_stop_hardware(chip); 5675 /* (7) */ 5676 pci_disable_device(pci); 5677 pci_save_state(pci); 5678 return 0; 5679 } 5680]]> 5681 </programlisting> 5682 </informalexample> 5683 </para> 5684 5685 <para> 5686 The scheme of the real resume job is as follows. 5687 5688 <orderedlist> 5689 <listitem><para>Retrieve the card and the chip data.</para></listitem> 5690 <listitem><para>Set up PCI. First, call <function>pci_restore_state()</function>. 5691 Then enable the pci device again by calling <function>pci_enable_device()</function>. 5692 Call <function>pci_set_master()</function> if necessary, too.</para></listitem> 5693 <listitem><para>Re-initialize the chip.</para></listitem> 5694 <listitem><para>Restore the saved registers if necessary.</para></listitem> 5695 <listitem><para>Resume the mixer, e.g. calling 5696 <function>snd_ac97_resume()</function>.</para></listitem> 5697 <listitem><para>Restart the hardware (if any).</para></listitem> 5698 <listitem><para>Call <function>snd_power_change_state()</function> with 5699 <constant>SNDRV_CTL_POWER_D0</constant> to notify the processes.</para></listitem> 5700 </orderedlist> 5701 </para> 5702 5703 <para> 5704 A typical code would be like: 5705 5706 <informalexample> 5707 <programlisting> 5708<![CDATA[ 5709 static int mychip_resume(struct pci_dev *pci) 5710 { 5711 /* (1) */ 5712 struct snd_card *card = pci_get_drvdata(pci); 5713 struct mychip *chip = card->private_data; 5714 /* (2) */ 5715 pci_restore_state(pci); 5716 pci_enable_device(pci); 5717 pci_set_master(pci); 5718 /* (3) */ 5719 snd_mychip_reinit_chip(chip); 5720 /* (4) */ 5721 snd_mychip_restore_registers(chip); 5722 /* (5) */ 5723 snd_ac97_resume(chip->ac97); 5724 /* (6) */ 5725 snd_mychip_restart_chip(chip); 5726 /* (7) */ 5727 snd_power_change_state(card, SNDRV_CTL_POWER_D0); 5728 return 0; 5729 } 5730]]> 5731 </programlisting> 5732 </informalexample> 5733 </para> 5734 5735 <para> 5736 As shown in the above, it's better to save registers after 5737 suspending the PCM operations via 5738 <function>snd_pcm_suspend_all()</function> or 5739 <function>snd_pcm_suspend()</function>. It means that the PCM 5740 streams are already stopped when the register snapshot is 5741 taken. But, remember that you don't have to restart the PCM 5742 stream in the resume callback. It'll be restarted via 5743 trigger call with <constant>SNDRV_PCM_TRIGGER_RESUME</constant> 5744 when necessary. 5745 </para> 5746 5747 <para> 5748 OK, we have all callbacks now. Let's set them up. In the 5749 initialization of the card, make sure that you can get the chip 5750 data from the card instance, typically via 5751 <structfield>private_data</structfield> field, in case you 5752 created the chip data individually. 5753 5754 <informalexample> 5755 <programlisting> 5756<![CDATA[ 5757 static int snd_mychip_probe(struct pci_dev *pci, 5758 const struct pci_device_id *pci_id) 5759 { 5760 .... 5761 struct snd_card *card; 5762 struct mychip *chip; 5763 int err; 5764 .... 5765 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, 5766 0, &card); 5767 .... 5768 chip = kzalloc(sizeof(*chip), GFP_KERNEL); 5769 .... 5770 card->private_data = chip; 5771 .... 5772 } 5773]]> 5774 </programlisting> 5775 </informalexample> 5776 5777 When you created the chip data with 5778 <function>snd_card_new()</function>, it's anyway accessible 5779 via <structfield>private_data</structfield> field. 5780 5781 <informalexample> 5782 <programlisting> 5783<![CDATA[ 5784 static int snd_mychip_probe(struct pci_dev *pci, 5785 const struct pci_device_id *pci_id) 5786 { 5787 .... 5788 struct snd_card *card; 5789 struct mychip *chip; 5790 int err; 5791 .... 5792 err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, 5793 sizeof(struct mychip), &card); 5794 .... 5795 chip = card->private_data; 5796 .... 5797 } 5798]]> 5799 </programlisting> 5800 </informalexample> 5801 5802 </para> 5803 5804 <para> 5805 If you need a space to save the registers, allocate the 5806 buffer for it here, too, since it would be fatal 5807 if you cannot allocate a memory in the suspend phase. 5808 The allocated buffer should be released in the corresponding 5809 destructor. 5810 </para> 5811 5812 <para> 5813 And next, set suspend/resume callbacks to the pci_driver. 5814 5815 <informalexample> 5816 <programlisting> 5817<![CDATA[ 5818 static struct pci_driver driver = { 5819 .name = KBUILD_MODNAME, 5820 .id_table = snd_my_ids, 5821 .probe = snd_my_probe, 5822 .remove = snd_my_remove, 5823 #ifdef CONFIG_PM 5824 .suspend = snd_my_suspend, 5825 .resume = snd_my_resume, 5826 #endif 5827 }; 5828]]> 5829 </programlisting> 5830 </informalexample> 5831 </para> 5832 5833 </chapter> 5834 5835 5836<!-- ****************************************************** --> 5837<!-- Module Parameters --> 5838<!-- ****************************************************** --> 5839 <chapter id="module-parameters"> 5840 <title>Module Parameters</title> 5841 <para> 5842 There are standard module options for ALSA. At least, each 5843 module should have the <parameter>index</parameter>, 5844 <parameter>id</parameter> and <parameter>enable</parameter> 5845 options. 5846 </para> 5847 5848 <para> 5849 If the module supports multiple cards (usually up to 5850 8 = <constant>SNDRV_CARDS</constant> cards), they should be 5851 arrays. The default initial values are defined already as 5852 constants for easier programming: 5853 5854 <informalexample> 5855 <programlisting> 5856<![CDATA[ 5857 static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX; 5858 static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR; 5859 static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP; 5860]]> 5861 </programlisting> 5862 </informalexample> 5863 </para> 5864 5865 <para> 5866 If the module supports only a single card, they could be single 5867 variables, instead. <parameter>enable</parameter> option is not 5868 always necessary in this case, but it would be better to have a 5869 dummy option for compatibility. 5870 </para> 5871 5872 <para> 5873 The module parameters must be declared with the standard 5874 <function>module_param()()</function>, 5875 <function>module_param_array()()</function> and 5876 <function>MODULE_PARM_DESC()</function> macros. 5877 </para> 5878 5879 <para> 5880 The typical coding would be like below: 5881 5882 <informalexample> 5883 <programlisting> 5884<![CDATA[ 5885 #define CARD_NAME "My Chip" 5886 5887 module_param_array(index, int, NULL, 0444); 5888 MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard."); 5889 module_param_array(id, charp, NULL, 0444); 5890 MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard."); 5891 module_param_array(enable, bool, NULL, 0444); 5892 MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard."); 5893]]> 5894 </programlisting> 5895 </informalexample> 5896 </para> 5897 5898 <para> 5899 Also, don't forget to define the module description, classes, 5900 license and devices. Especially, the recent modprobe requires to 5901 define the module license as GPL, etc., otherwise the system is 5902 shown as <quote>tainted</quote>. 5903 5904 <informalexample> 5905 <programlisting> 5906<![CDATA[ 5907 MODULE_DESCRIPTION("My Chip"); 5908 MODULE_LICENSE("GPL"); 5909 MODULE_SUPPORTED_DEVICE("{{Vendor,My Chip Name}}"); 5910]]> 5911 </programlisting> 5912 </informalexample> 5913 </para> 5914 5915 </chapter> 5916 5917 5918<!-- ****************************************************** --> 5919<!-- How To Put Your Driver --> 5920<!-- ****************************************************** --> 5921 <chapter id="how-to-put-your-driver"> 5922 <title>How To Put Your Driver Into ALSA Tree</title> 5923 <section> 5924 <title>General</title> 5925 <para> 5926 So far, you've learned how to write the driver codes. 5927 And you might have a question now: how to put my own 5928 driver into the ALSA driver tree? 5929 Here (finally :) the standard procedure is described briefly. 5930 </para> 5931 5932 <para> 5933 Suppose that you create a new PCI driver for the card 5934 <quote>xyz</quote>. The card module name would be 5935 snd-xyz. The new driver is usually put into the alsa-driver 5936 tree, <filename>alsa-driver/pci</filename> directory in 5937 the case of PCI cards. 5938 Then the driver is evaluated, audited and tested 5939 by developers and users. After a certain time, the driver 5940 will go to the alsa-kernel tree (to the corresponding directory, 5941 such as <filename>alsa-kernel/pci</filename>) and eventually 5942 will be integrated into the Linux 2.6 tree (the directory would be 5943 <filename>linux/sound/pci</filename>). 5944 </para> 5945 5946 <para> 5947 In the following sections, the driver code is supposed 5948 to be put into alsa-driver tree. The two cases are covered: 5949 a driver consisting of a single source file and one consisting 5950 of several source files. 5951 </para> 5952 </section> 5953 5954 <section> 5955 <title>Driver with A Single Source File</title> 5956 <para> 5957 <orderedlist> 5958 <listitem> 5959 <para> 5960 Modify alsa-driver/pci/Makefile 5961 </para> 5962 5963 <para> 5964 Suppose you have a file xyz.c. Add the following 5965 two lines 5966 <informalexample> 5967 <programlisting> 5968<![CDATA[ 5969 snd-xyz-objs := xyz.o 5970 obj-$(CONFIG_SND_XYZ) += snd-xyz.o 5971]]> 5972 </programlisting> 5973 </informalexample> 5974 </para> 5975 </listitem> 5976 5977 <listitem> 5978 <para> 5979 Create the Kconfig entry 5980 </para> 5981 5982 <para> 5983 Add the new entry of Kconfig for your xyz driver. 5984 <informalexample> 5985 <programlisting> 5986<![CDATA[ 5987 config SND_XYZ 5988 tristate "Foobar XYZ" 5989 depends on SND 5990 select SND_PCM 5991 help 5992 Say Y here to include support for Foobar XYZ soundcard. 5993 5994 To compile this driver as a module, choose M here: the module 5995 will be called snd-xyz. 5996]]> 5997 </programlisting> 5998 </informalexample> 5999 6000 the line, select SND_PCM, specifies that the driver xyz supports 6001 PCM. In addition to SND_PCM, the following components are 6002 supported for select command: 6003 SND_RAWMIDI, SND_TIMER, SND_HWDEP, SND_MPU401_UART, 6004 SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, SND_AC97_CODEC. 6005 Add the select command for each supported component. 6006 </para> 6007 6008 <para> 6009 Note that some selections imply the lowlevel selections. 6010 For example, PCM includes TIMER, MPU401_UART includes RAWMIDI, 6011 AC97_CODEC includes PCM, and OPL3_LIB includes HWDEP. 6012 You don't need to give the lowlevel selections again. 6013 </para> 6014 6015 <para> 6016 For the details of Kconfig script, refer to the kbuild 6017 documentation. 6018 </para> 6019 6020 </listitem> 6021 6022 <listitem> 6023 <para> 6024 Run cvscompile script to re-generate the configure script and 6025 build the whole stuff again. 6026 </para> 6027 </listitem> 6028 </orderedlist> 6029 </para> 6030 </section> 6031 6032 <section> 6033 <title>Drivers with Several Source Files</title> 6034 <para> 6035 Suppose that the driver snd-xyz have several source files. 6036 They are located in the new subdirectory, 6037 pci/xyz. 6038 6039 <orderedlist> 6040 <listitem> 6041 <para> 6042 Add a new directory (<filename>xyz</filename>) in 6043 <filename>alsa-driver/pci/Makefile</filename> as below 6044 6045 <informalexample> 6046 <programlisting> 6047<![CDATA[ 6048 obj-$(CONFIG_SND) += xyz/ 6049]]> 6050 </programlisting> 6051 </informalexample> 6052 </para> 6053 </listitem> 6054 6055 <listitem> 6056 <para> 6057 Under the directory <filename>xyz</filename>, create a Makefile 6058 6059 <example> 6060 <title>Sample Makefile for a driver xyz</title> 6061 <programlisting> 6062<![CDATA[ 6063 ifndef SND_TOPDIR 6064 SND_TOPDIR=../.. 6065 endif 6066 6067 include $(SND_TOPDIR)/toplevel.config 6068 include $(SND_TOPDIR)/Makefile.conf 6069 6070 snd-xyz-objs := xyz.o abc.o def.o 6071 6072 obj-$(CONFIG_SND_XYZ) += snd-xyz.o 6073 6074 include $(SND_TOPDIR)/Rules.make 6075]]> 6076 </programlisting> 6077 </example> 6078 </para> 6079 </listitem> 6080 6081 <listitem> 6082 <para> 6083 Create the Kconfig entry 6084 </para> 6085 6086 <para> 6087 This procedure is as same as in the last section. 6088 </para> 6089 </listitem> 6090 6091 <listitem> 6092 <para> 6093 Run cvscompile script to re-generate the configure script and 6094 build the whole stuff again. 6095 </para> 6096 </listitem> 6097 </orderedlist> 6098 </para> 6099 </section> 6100 6101 </chapter> 6102 6103<!-- ****************************************************** --> 6104<!-- Useful Functions --> 6105<!-- ****************************************************** --> 6106 <chapter id="useful-functions"> 6107 <title>Useful Functions</title> 6108 6109 <section id="useful-functions-snd-printk"> 6110 <title><function>snd_printk()</function> and friends</title> 6111 <para> 6112 ALSA provides a verbose version of the 6113 <function>printk()</function> function. If a kernel config 6114 <constant>CONFIG_SND_VERBOSE_PRINTK</constant> is set, this 6115 function prints the given message together with the file name 6116 and the line of the caller. The <constant>KERN_XXX</constant> 6117 prefix is processed as 6118 well as the original <function>printk()</function> does, so it's 6119 recommended to add this prefix, e.g. 6120 6121 <informalexample> 6122 <programlisting> 6123<![CDATA[ 6124 snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\n"); 6125]]> 6126 </programlisting> 6127 </informalexample> 6128 </para> 6129 6130 <para> 6131 There are also <function>printk()</function>'s for 6132 debugging. <function>snd_printd()</function> can be used for 6133 general debugging purposes. If 6134 <constant>CONFIG_SND_DEBUG</constant> is set, this function is 6135 compiled, and works just like 6136 <function>snd_printk()</function>. If the ALSA is compiled 6137 without the debugging flag, it's ignored. 6138 </para> 6139 6140 <para> 6141 <function>snd_printdd()</function> is compiled in only when 6142 <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is set. Please note 6143 that <constant>CONFIG_SND_DEBUG_VERBOSE</constant> is not set as default 6144 even if you configure the alsa-driver with 6145 <option>--with-debug=full</option> option. You need to give 6146 explicitly <option>--with-debug=detect</option> option instead. 6147 </para> 6148 </section> 6149 6150 <section id="useful-functions-snd-bug"> 6151 <title><function>snd_BUG()</function></title> 6152 <para> 6153 It shows the <computeroutput>BUG?</computeroutput> message and 6154 stack trace as well as <function>snd_BUG_ON</function> at the point. 6155 It's useful to show that a fatal error happens there. 6156 </para> 6157 <para> 6158 When no debug flag is set, this macro is ignored. 6159 </para> 6160 </section> 6161 6162 <section id="useful-functions-snd-bug-on"> 6163 <title><function>snd_BUG_ON()</function></title> 6164 <para> 6165 <function>snd_BUG_ON()</function> macro is similar with 6166 <function>WARN_ON()</function> macro. For example, 6167 6168 <informalexample> 6169 <programlisting> 6170<![CDATA[ 6171 snd_BUG_ON(!pointer); 6172]]> 6173 </programlisting> 6174 </informalexample> 6175 6176 or it can be used as the condition, 6177 <informalexample> 6178 <programlisting> 6179<![CDATA[ 6180 if (snd_BUG_ON(non_zero_is_bug)) 6181 return -EINVAL; 6182]]> 6183 </programlisting> 6184 </informalexample> 6185 6186 </para> 6187 6188 <para> 6189 The macro takes an conditional expression to evaluate. 6190 When <constant>CONFIG_SND_DEBUG</constant>, is set, if the 6191 expression is non-zero, it shows the warning message such as 6192 <computeroutput>BUG? (xxx)</computeroutput> 6193 normally followed by stack trace. 6194 6195 In both cases it returns the evaluated value. 6196 </para> 6197 6198 </section> 6199 6200 </chapter> 6201 6202 6203<!-- ****************************************************** --> 6204<!-- Acknowledgments --> 6205<!-- ****************************************************** --> 6206 <chapter id="acknowledgments"> 6207 <title>Acknowledgments</title> 6208 <para> 6209 I would like to thank Phil Kerr for his help for improvement and 6210 corrections of this document. 6211 </para> 6212 <para> 6213 Kevin Conder reformatted the original plain-text to the 6214 DocBook format. 6215 </para> 6216 <para> 6217 Giuliano Pochini corrected typos and contributed the example codes 6218 in the hardware constraints section. 6219 </para> 6220 </chapter> 6221</book> 6222