^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) ======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) Writing an ALSA Driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) :Author: Takashi Iwai <tiwai@suse.de>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) Preface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) =======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) This document describes how to write an `ALSA (Advanced Linux Sound
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) Architecture) <http://www.alsa-project.org/>`__ driver. The document
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) focuses mainly on PCI soundcards. In the case of other device types, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) API might be different, too. However, at least the ALSA kernel API is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) consistent, and therefore it would be still a bit help for writing them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) This document targets people who already have enough C language skills
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) and have basic linux kernel programming knowledge. This document doesn't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) explain the general topic of linux kernel coding and doesn't cover
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) low-level driver implementation details. It only describes the standard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) way to write a PCI sound driver on ALSA.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) This document is still a draft version. Any feedback and corrections,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) please!!
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) File Tree Structure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) ===================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) General
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) -------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) The file tree structure of ALSA driver is depicted below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) sound
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) /core
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) /oss
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) /seq
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) /oss
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) /include
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) /drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) /mpu401
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) /opl3
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) /i2c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) /synth
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) /emux
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) /pci
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) /(cards)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) /isa
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) /(cards)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) /arm
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) /ppc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) /sparc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) /usb
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) /pcmcia /(cards)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) /soc
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) /oss
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) core directory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) --------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) This directory contains the middle layer which is the heart of ALSA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) drivers. In this directory, the native ALSA modules are stored. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) sub-directories contain different modules and are dependent upon the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) kernel config.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) core/oss
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) ~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) The codes for PCM and mixer OSS emulation modules are stored in this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) directory. The rawmidi OSS emulation is included in the ALSA rawmidi
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) code since it's quite small. The sequencer code is stored in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) ``core/seq/oss`` directory (see `below <#core-seq-oss>`__).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) core/seq
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) ~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) This directory and its sub-directories are for the ALSA sequencer. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) directory contains the sequencer core and primary sequencer modules such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) like snd-seq-midi, snd-seq-virmidi, etc. They are compiled only when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) ``CONFIG_SND_SEQUENCER`` is set in the kernel config.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) core/seq/oss
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) ~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) This contains the OSS sequencer emulation codes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) include directory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) -----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) This is the place for the public header files of ALSA drivers, which are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) to be exported to user-space, or included by several files at different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) directories. Basically, the private header files should not be placed in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) this directory, but you may still find files there, due to historical
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) reasons :)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) drivers directory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) -----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) This directory contains code shared among different drivers on different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) architectures. They are hence supposed not to be architecture-specific.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) For example, the dummy pcm driver and the serial MIDI driver are found
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) in this directory. In the sub-directories, there is code for components
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) which are independent from bus and cpu architectures.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) drivers/mpu401
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) ~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) The MPU401 and MPU401-UART modules are stored here.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) drivers/opl3 and opl4
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) ~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) The OPL3 and OPL4 FM-synth stuff is found here.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) i2c directory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) -------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) This contains the ALSA i2c components.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) Although there is a standard i2c layer on Linux, ALSA has its own i2c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) code for some cards, because the soundcard needs only a simple operation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) and the standard i2c API is too complicated for such a purpose.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) synth directory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) ---------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) This contains the synth middle-level modules.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) So far, there is only Emu8000/Emu10k1 synth driver under the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) ``synth/emux`` sub-directory.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) pci directory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) -------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) This directory and its sub-directories hold the top-level card modules
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) for PCI soundcards and the code specific to the PCI BUS.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) The drivers compiled from a single file are stored directly in the pci
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) directory, while the drivers with several source files are stored on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) their own sub-directory (e.g. emu10k1, ice1712).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) isa directory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) -------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) This directory and its sub-directories hold the top-level card modules
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) for ISA soundcards.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) arm, ppc, and sparc directories
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) -------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) They are used for top-level card modules which are specific to one of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) these architectures.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) usb directory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) -------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) This directory contains the USB-audio driver. In the latest version, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) USB MIDI driver is integrated in the usb-audio driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) pcmcia directory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) ----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) The PCMCIA, especially PCCard drivers will go here. CardBus drivers will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) be in the pci directory, because their API is identical to that of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) standard PCI cards.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) soc directory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) -------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) This directory contains the codes for ASoC (ALSA System on Chip)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) layer including ASoC core, codec and machine drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) oss directory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) -------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) Here contains OSS/Lite codes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) All codes have been deprecated except for dmasound on m68k as of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) writing this.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) Basic Flow for PCI Drivers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) ==========================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) Outline
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) -------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) The minimum flow for PCI soundcards is as follows:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) - define the PCI ID table (see the section `PCI Entries`_).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) - create ``probe`` callback.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) - create ``remove`` callback.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) - create a struct pci_driver structure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) containing the three pointers above.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) - create an ``init`` function just calling the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) :c:func:`pci_register_driver()` to register the pci_driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) table defined above.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) - create an ``exit`` function to call the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) :c:func:`pci_unregister_driver()` function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) Full Code Example
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) -----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) The code example is shown below. Some parts are kept unimplemented at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) this moment but will be filled in the next sections. The numbers in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) comment lines of the :c:func:`snd_mychip_probe()` function refer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) to details explained in the following section.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) #include <linux/init.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) #include <linux/pci.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) #include <linux/slab.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) #include <sound/core.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) #include <sound/initval.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) /* module parameters (see "Module Parameters") */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) /* SNDRV_CARDS: maximum number of cards supported by this module */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) static bool enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) /* definition of the chip-specific record */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) struct mychip {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) struct snd_card *card;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) /* the rest of the implementation will be in section
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) * "PCI Resource Management"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237) /* chip-specific destructor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) * (see "PCI Resource Management")
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) static int snd_mychip_free(struct mychip *chip)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) .... /* will be implemented later... */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245) /* component-destructor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) * (see "Management of Cards and Components")
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) static int snd_mychip_dev_free(struct snd_device *device)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) return snd_mychip_free(device->device_data);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) /* chip-specific constructor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) * (see "Management of Cards and Components")
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) static int snd_mychip_create(struct snd_card *card,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) struct pci_dev *pci,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) struct mychip **rchip)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) struct mychip *chip;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) int err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) static const struct snd_device_ops ops = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) .dev_free = snd_mychip_dev_free,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) *rchip = NULL;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) /* check PCI availability here
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269) * (see "PCI Resource Management")
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) /* allocate a chip-specific data with zero filled */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) chip = kzalloc(sizeof(*chip), GFP_KERNEL);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) if (chip == NULL)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) return -ENOMEM;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) chip->card = card;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) /* rest of initialization here; will be implemented
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) * later, see "PCI Resource Management"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285) err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) if (err < 0) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) snd_mychip_free(chip);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) return err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) *rchip = chip;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) /* constructor -- see "Driver Constructor" sub-section */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) static int snd_mychip_probe(struct pci_dev *pci,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) const struct pci_device_id *pci_id)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) static int dev;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) struct snd_card *card;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) struct mychip *chip;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) int err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) /* (1) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) if (dev >= SNDRV_CARDS)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) return -ENODEV;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) if (!enable[dev]) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) dev++;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) return -ENOENT;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) /* (2) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) 0, &card);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) if (err < 0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) return err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) /* (3) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) err = snd_mychip_create(card, pci, &chip);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) if (err < 0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) goto error;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323) /* (4) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) strcpy(card->driver, "My Chip");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) strcpy(card->shortname, "My Own Chip 123");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) sprintf(card->longname, "%s at 0x%lx irq %i",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) card->shortname, chip->port, chip->irq);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) /* (5) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) .... /* implemented later */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) /* (6) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) err = snd_card_register(card);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) if (err < 0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335) goto error;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) /* (7) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338) pci_set_drvdata(pci, card);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) dev++;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) error:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343) snd_card_free(card);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) return err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) /* destructor -- see the "Destructor" sub-section */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) static void snd_mychip_remove(struct pci_dev *pci)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350) snd_card_free(pci_get_drvdata(pci));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) Driver Constructor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356) ------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) The real constructor of PCI drivers is the ``probe`` callback. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) ``probe`` callback and other component-constructors which are called
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) from the ``probe`` callback cannot be used with the ``__init`` prefix
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) because any PCI device could be a hotplug device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) In the ``probe`` callback, the following scheme is often used.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365) 1) Check and increment the device index.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) static int dev;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372) if (dev >= SNDRV_CARDS)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) return -ENODEV;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374) if (!enable[dev]) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) dev++;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) return -ENOENT;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380) where ``enable[dev]`` is the module option.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) Each time the ``probe`` callback is called, check the availability of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383) the device. If not available, simply increment the device index and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) returns. dev will be incremented also later (`step 7
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385) <#set-the-pci-driver-data-and-return-zero>`__).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) 2) Create a card instance
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) ~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) struct snd_card *card;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) int err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396) 0, &card);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) The details will be explained in the section `Management of Cards and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) Components`_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) 3) Create a main component
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) ~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) In this part, the PCI resources are allocated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) struct mychip *chip;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 411) err = snd_mychip_create(card, pci, &chip);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 412) if (err < 0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 413) goto error;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 414)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 415) The details will be explained in the section `PCI Resource
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 416) Management`_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 417)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 418) When something goes wrong, the probe function needs to deal with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 419) error. In this example, we have a single error handling path placed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 420) at the end of the function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 421)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 422) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 423)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 424) error:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 425) snd_card_free(card);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 426) return err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 427)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 428) Since each component can be properly freed, the single
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 429) :c:func:`snd_card_free()` call should suffice in most cases.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 430)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 431)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 432) 4) Set the driver ID and name strings.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 433) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 434)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 435) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 436)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 437) strcpy(card->driver, "My Chip");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 438) strcpy(card->shortname, "My Own Chip 123");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 439) sprintf(card->longname, "%s at 0x%lx irq %i",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 440) card->shortname, chip->port, chip->irq);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 441)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 442) The driver field holds the minimal ID string of the chip. This is used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 443) by alsa-lib's configurator, so keep it simple but unique. Even the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 444) same driver can have different driver IDs to distinguish the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 445) functionality of each chip type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 446)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 447) The shortname field is a string shown as more verbose name. The longname
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 448) field contains the information shown in ``/proc/asound/cards``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 449)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 450) 5) Create other components, such as mixer, MIDI, etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 451) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 452)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 453) Here you define the basic components such as `PCM <#PCM-Interface>`__,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 454) mixer (e.g. `AC97 <#API-for-AC97-Codec>`__), MIDI (e.g.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 455) `MPU-401 <#MIDI-MPU401-UART-Interface>`__), and other interfaces.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 456) Also, if you want a `proc file <#Proc-Interface>`__, define it here,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 457) too.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 458)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 459) 6) Register the card instance.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 460) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 461)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 462) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 463)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 464) err = snd_card_register(card);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 465) if (err < 0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 466) goto error;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 467)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 468) Will be explained in the section `Management of Cards and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 469) Components`_, too.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 470)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 471) 7) Set the PCI driver data and return zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 472) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 473)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 474) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 475)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 476) pci_set_drvdata(pci, card);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 477) dev++;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 478) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 479)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 480) In the above, the card record is stored. This pointer is used in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 481) remove callback and power-management callbacks, too.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 482)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 483) Destructor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 484) ----------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 485)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 486) The destructor, remove callback, simply releases the card instance. Then
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 487) the ALSA middle layer will release all the attached components
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 488) automatically.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 489)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 490) It would be typically just calling :c:func:`snd_card_free()`:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 491)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 492) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 493)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 494) static void snd_mychip_remove(struct pci_dev *pci)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 495) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 496) snd_card_free(pci_get_drvdata(pci));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 497) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 498)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 499)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 500) The above code assumes that the card pointer is set to the PCI driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 501) data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 502)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 503) Header Files
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 504) ------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 505)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 506) For the above example, at least the following include files are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 507) necessary.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 508)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 509) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 510)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 511) #include <linux/init.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 512) #include <linux/pci.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 513) #include <linux/slab.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 514) #include <sound/core.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 515) #include <sound/initval.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 516)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 517) where the last one is necessary only when module options are defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 518) in the source file. If the code is split into several files, the files
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 519) without module options don't need them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 520)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 521) In addition to these headers, you'll need ``<linux/interrupt.h>`` for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 522) interrupt handling, and ``<linux/io.h>`` for I/O access. If you use the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 523) :c:func:`mdelay()` or :c:func:`udelay()` functions, you'll need
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 524) to include ``<linux/delay.h>`` too.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 525)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 526) The ALSA interfaces like the PCM and control APIs are defined in other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 527) ``<sound/xxx.h>`` header files. They have to be included after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 528) ``<sound/core.h>``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 529)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 530) Management of Cards and Components
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 531) ==================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 532)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 533) Card Instance
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 534) -------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 535)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 536) For each soundcard, a “card” record must be allocated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 537)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 538) A card record is the headquarters of the soundcard. It manages the whole
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 539) list of devices (components) on the soundcard, such as PCM, mixers,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 540) MIDI, synthesizer, and so on. Also, the card record holds the ID and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 541) name strings of the card, manages the root of proc files, and controls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 542) the power-management states and hotplug disconnections. The component
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 543) list on the card record is used to manage the correct release of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 544) resources at destruction.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 545)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 546) As mentioned above, to create a card instance, call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 547) :c:func:`snd_card_new()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 548)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 549) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 550)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 551) struct snd_card *card;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 552) int err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 553) err = snd_card_new(&pci->dev, index, id, module, extra_size, &card);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 554)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 555)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 556) The function takes six arguments: the parent device pointer, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 557) card-index number, the id string, the module pointer (usually
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 558) ``THIS_MODULE``), the size of extra-data space, and the pointer to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 559) return the card instance. The extra_size argument is used to allocate
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 560) card->private_data for the chip-specific data. Note that these data are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 561) allocated by :c:func:`snd_card_new()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 562)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 563) The first argument, the pointer of struct device, specifies the parent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 564) device. For PCI devices, typically ``&pci->`` is passed there.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 565)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 566) Components
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 567) ----------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 568)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 569) After the card is created, you can attach the components (devices) to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 570) the card instance. In an ALSA driver, a component is represented as a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 571) struct snd_device object. A component
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 572) can be a PCM instance, a control interface, a raw MIDI interface, etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 573) Each such instance has one component entry.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 574)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 575) A component can be created via :c:func:`snd_device_new()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 576) function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 577)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 578) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 579)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 580) snd_device_new(card, SNDRV_DEV_XXX, chip, &ops);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 581)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 582) This takes the card pointer, the device-level (``SNDRV_DEV_XXX``), the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 583) data pointer, and the callback pointers (``&ops``). The device-level
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 584) defines the type of components and the order of registration and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 585) de-registration. For most components, the device-level is already
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 586) defined. For a user-defined component, you can use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 587) ``SNDRV_DEV_LOWLEVEL``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 588)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 589) This function itself doesn't allocate the data space. The data must be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 590) allocated manually beforehand, and its pointer is passed as the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 591) argument. This pointer (``chip`` in the above example) is used as the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 592) identifier for the instance.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 593)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 594) Each pre-defined ALSA component such as ac97 and pcm calls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 595) :c:func:`snd_device_new()` inside its constructor. The destructor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 596) for each component is defined in the callback pointers. Hence, you don't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 597) need to take care of calling a destructor for such a component.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 598)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 599) If you wish to create your own component, you need to set the destructor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 600) function to the dev_free callback in the ``ops``, so that it can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 601) released automatically via :c:func:`snd_card_free()`. The next
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 602) example will show an implementation of chip-specific data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 603)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 604) Chip-Specific Data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 605) ------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 606)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 607) Chip-specific information, e.g. the I/O port address, its resource
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 608) pointer, or the irq number, is stored in the chip-specific record.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 609)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 610) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 611)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 612) struct mychip {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 613) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 614) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 615)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 616)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 617) In general, there are two ways of allocating the chip record.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 618)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 619) 1. Allocating via :c:func:`snd_card_new()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 620) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 621)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 622) As mentioned above, you can pass the extra-data-length to the 5th
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 623) argument of :c:func:`snd_card_new()`, i.e.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 624)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 625) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 626)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 627) err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 628) sizeof(struct mychip), &card);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 629)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 630) struct mychip is the type of the chip record.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 631)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 632) In return, the allocated record can be accessed as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 633)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 634) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 635)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 636) struct mychip *chip = card->private_data;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 637)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 638) With this method, you don't have to allocate twice. The record is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 639) released together with the card instance.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 640)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 641) 2. Allocating an extra device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 642) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 643)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 644) After allocating a card instance via :c:func:`snd_card_new()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 645) (with ``0`` on the 4th arg), call :c:func:`kzalloc()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 646)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 647) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 648)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 649) struct snd_card *card;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 650) struct mychip *chip;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 651) err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 652) 0, &card);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 653) .....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 654) chip = kzalloc(sizeof(*chip), GFP_KERNEL);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 655)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 656) The chip record should have the field to hold the card pointer at least,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 657)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 658) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 659)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 660) struct mychip {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 661) struct snd_card *card;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 662) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 663) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 664)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 665)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 666) Then, set the card pointer in the returned chip instance.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 667)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 668) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 669)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 670) chip->card = card;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 671)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 672) Next, initialize the fields, and register this chip record as a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 673) low-level device with a specified ``ops``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 674)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 675) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 676)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 677) static const struct snd_device_ops ops = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 678) .dev_free = snd_mychip_dev_free,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 679) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 680) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 681) snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 682)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 683) :c:func:`snd_mychip_dev_free()` is the device-destructor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 684) function, which will call the real destructor.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 685)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 686) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 687)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 688) static int snd_mychip_dev_free(struct snd_device *device)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 689) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 690) return snd_mychip_free(device->device_data);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 691) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 692)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 693) where :c:func:`snd_mychip_free()` is the real destructor.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 694)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 695) The demerit of this method is the obviously more amount of codes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 696) The merit is, however, you can trigger the own callback at registering
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 697) and disconnecting the card via setting in snd_device_ops.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 698) About the registering and disconnecting the card, see the subsections
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 699) below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 700)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 701)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 702) Registration and Release
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 703) ------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 704)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 705) After all components are assigned, register the card instance by calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 706) :c:func:`snd_card_register()`. Access to the device files is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 707) enabled at this point. That is, before
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 708) :c:func:`snd_card_register()` is called, the components are safely
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 709) inaccessible from external side. If this call fails, exit the probe
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 710) function after releasing the card via :c:func:`snd_card_free()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 711)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 712) For releasing the card instance, you can call simply
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 713) :c:func:`snd_card_free()`. As mentioned earlier, all components
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 714) are released automatically by this call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 715)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 716) For a device which allows hotplugging, you can use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 717) :c:func:`snd_card_free_when_closed()`. This one will postpone
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 718) the destruction until all devices are closed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 719)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 720) PCI Resource Management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 721) =======================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 722)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 723) Full Code Example
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 724) -----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 725)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 726) In this section, we'll complete the chip-specific constructor,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 727) destructor and PCI entries. Example code is shown first, below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 728)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 729) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 730)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 731) struct mychip {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 732) struct snd_card *card;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 733) struct pci_dev *pci;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 734)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 735) unsigned long port;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 736) int irq;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 737) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 738)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 739) static int snd_mychip_free(struct mychip *chip)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 740) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 741) /* disable hardware here if any */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 742) .... /* (not implemented in this document) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 743)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 744) /* release the irq */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 745) if (chip->irq >= 0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 746) free_irq(chip->irq, chip);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 747) /* release the I/O ports & memory */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 748) pci_release_regions(chip->pci);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 749) /* disable the PCI entry */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 750) pci_disable_device(chip->pci);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 751) /* release the data */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 752) kfree(chip);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 753) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 754) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 755)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 756) /* chip-specific constructor */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 757) static int snd_mychip_create(struct snd_card *card,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 758) struct pci_dev *pci,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 759) struct mychip **rchip)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 760) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 761) struct mychip *chip;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 762) int err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 763) static const struct snd_device_ops ops = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 764) .dev_free = snd_mychip_dev_free,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 765) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 766)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 767) *rchip = NULL;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 768)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 769) /* initialize the PCI entry */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 770) err = pci_enable_device(pci);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 771) if (err < 0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 772) return err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 773) /* check PCI availability (28bit DMA) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 774) if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 775) pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 776) printk(KERN_ERR "error to set 28bit mask DMA\n");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 777) pci_disable_device(pci);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 778) return -ENXIO;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 779) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 780)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 781) chip = kzalloc(sizeof(*chip), GFP_KERNEL);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 782) if (chip == NULL) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 783) pci_disable_device(pci);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 784) return -ENOMEM;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 785) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 786)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 787) /* initialize the stuff */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 788) chip->card = card;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 789) chip->pci = pci;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 790) chip->irq = -1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 791)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 792) /* (1) PCI resource allocation */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 793) err = pci_request_regions(pci, "My Chip");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 794) if (err < 0) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 795) kfree(chip);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 796) pci_disable_device(pci);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 797) return err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 798) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 799) chip->port = pci_resource_start(pci, 0);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 800) if (request_irq(pci->irq, snd_mychip_interrupt,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 801) IRQF_SHARED, KBUILD_MODNAME, chip)) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 802) printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 803) snd_mychip_free(chip);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 804) return -EBUSY;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 805) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 806) chip->irq = pci->irq;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 807) card->sync_irq = chip->irq;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 808)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 809) /* (2) initialization of the chip hardware */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 810) .... /* (not implemented in this document) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 811)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 812) err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 813) if (err < 0) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 814) snd_mychip_free(chip);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 815) return err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 816) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 817)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 818) *rchip = chip;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 819) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 820) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 821)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 822) /* PCI IDs */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 823) static struct pci_device_id snd_mychip_ids[] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 824) { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 825) PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 826) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 827) { 0, }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 828) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 829) MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 830)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 831) /* pci_driver definition */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 832) static struct pci_driver driver = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 833) .name = KBUILD_MODNAME,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 834) .id_table = snd_mychip_ids,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 835) .probe = snd_mychip_probe,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 836) .remove = snd_mychip_remove,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 837) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 838)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 839) /* module initialization */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 840) static int __init alsa_card_mychip_init(void)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 841) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 842) return pci_register_driver(&driver);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 843) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 844)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 845) /* module clean up */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 846) static void __exit alsa_card_mychip_exit(void)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 847) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 848) pci_unregister_driver(&driver);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 849) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 850)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 851) module_init(alsa_card_mychip_init)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 852) module_exit(alsa_card_mychip_exit)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 853)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 854) EXPORT_NO_SYMBOLS; /* for old kernels only */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 855)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 856) Some Hafta's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 857) ------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 858)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 859) The allocation of PCI resources is done in the ``probe`` function, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 860) usually an extra :c:func:`xxx_create()` function is written for this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 861) purpose.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 862)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 863) In the case of PCI devices, you first have to call the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 864) :c:func:`pci_enable_device()` function before allocating
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 865) resources. Also, you need to set the proper PCI DMA mask to limit the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 866) accessed I/O range. In some cases, you might need to call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 867) :c:func:`pci_set_master()` function, too.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 868)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 869) Suppose the 28bit mask, and the code to be added would be like:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 870)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 871) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 872)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 873) err = pci_enable_device(pci);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 874) if (err < 0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 875) return err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 876) if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 ||
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 877) pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 878) printk(KERN_ERR "error to set 28bit mask DMA\n");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 879) pci_disable_device(pci);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 880) return -ENXIO;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 881) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 882)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 883)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 884) Resource Allocation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 885) -------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 886)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 887) The allocation of I/O ports and irqs is done via standard kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 888) functions. These resources must be released in the destructor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 889) function (see below).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 890)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 891) Now assume that the PCI device has an I/O port with 8 bytes and an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 892) interrupt. Then struct mychip will have the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 893) following fields:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 894)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 895) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 896)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 897) struct mychip {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 898) struct snd_card *card;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 899)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 900) unsigned long port;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 901) int irq;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 902) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 903)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 904)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 905) For an I/O port (and also a memory region), you need to have the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 906) resource pointer for the standard resource management. For an irq, you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 907) have to keep only the irq number (integer). But you need to initialize
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 908) this number as -1 before actual allocation, since irq 0 is valid. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 909) port address and its resource pointer can be initialized as null by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 910) :c:func:`kzalloc()` automatically, so you don't have to take care of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 911) resetting them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 912)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 913) The allocation of an I/O port is done like this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 914)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 915) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 916)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 917) err = pci_request_regions(pci, "My Chip");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 918) if (err < 0) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 919) kfree(chip);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 920) pci_disable_device(pci);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 921) return err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 922) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 923) chip->port = pci_resource_start(pci, 0);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 924)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 925) It will reserve the I/O port region of 8 bytes of the given PCI device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 926) The returned value, ``chip->res_port``, is allocated via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 927) :c:func:`kmalloc()` by :c:func:`request_region()`. The pointer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 928) must be released via :c:func:`kfree()`, but there is a problem with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 929) this. This issue will be explained later.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 930)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 931) The allocation of an interrupt source is done like this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 932)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 933) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 934)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 935) if (request_irq(pci->irq, snd_mychip_interrupt,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 936) IRQF_SHARED, KBUILD_MODNAME, chip)) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 937) printk(KERN_ERR "cannot grab irq %d\n", pci->irq);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 938) snd_mychip_free(chip);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 939) return -EBUSY;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 940) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 941) chip->irq = pci->irq;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 942)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 943) where :c:func:`snd_mychip_interrupt()` is the interrupt handler
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 944) defined `later <#pcm-interface-interrupt-handler>`__. Note that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 945) ``chip->irq`` should be defined only when :c:func:`request_irq()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 946) succeeded.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 947)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 948) On the PCI bus, interrupts can be shared. Thus, ``IRQF_SHARED`` is used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 949) as the interrupt flag of :c:func:`request_irq()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 950)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 951) The last argument of :c:func:`request_irq()` is the data pointer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 952) passed to the interrupt handler. Usually, the chip-specific record is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 953) used for that, but you can use what you like, too.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 954)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 955) I won't give details about the interrupt handler at this point, but at
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 956) least its appearance can be explained now. The interrupt handler looks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 957) usually like the following:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 958)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 959) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 960)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 961) static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 962) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 963) struct mychip *chip = dev_id;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 964) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 965) return IRQ_HANDLED;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 966) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 967)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 968) After requesting the IRQ, you can passed it to ``card->sync_irq``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 969) field:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 970) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 971)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 972) card->irq = chip->irq;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 973)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 974) This allows PCM core automatically performing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 975) :c:func:`synchronize_irq()` at the necessary timing like ``hw_free``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 976) See the later section `sync_stop callback`_ for details.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 977)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 978) Now let's write the corresponding destructor for the resources above.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 979) The role of destructor is simple: disable the hardware (if already
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 980) activated) and release the resources. So far, we have no hardware part,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 981) so the disabling code is not written here.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 982)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 983) To release the resources, the “check-and-release” method is a safer way.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 984) For the interrupt, do like this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 985)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 986) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 987)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 988) if (chip->irq >= 0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 989) free_irq(chip->irq, chip);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 990)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 991) Since the irq number can start from 0, you should initialize
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 992) ``chip->irq`` with a negative value (e.g. -1), so that you can check
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 993) the validity of the irq number as above.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 994)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 995) When you requested I/O ports or memory regions via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 996) :c:func:`pci_request_region()` or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 997) :c:func:`pci_request_regions()` like in this example, release the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 998) resource(s) using the corresponding function,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 999) :c:func:`pci_release_region()` or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1000) :c:func:`pci_release_regions()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1001)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1002) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1003)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1004) pci_release_regions(chip->pci);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1005)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1006) When you requested manually via :c:func:`request_region()` or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1007) :c:func:`request_mem_region()`, you can release it via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1008) :c:func:`release_resource()`. Suppose that you keep the resource
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1009) pointer returned from :c:func:`request_region()` in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1010) chip->res_port, the release procedure looks like:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1011)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1012) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1013)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1014) release_and_free_resource(chip->res_port);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1015)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1016) Don't forget to call :c:func:`pci_disable_device()` before the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1017) end.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1018)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1019) And finally, release the chip-specific record.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1020)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1021) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1022)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1023) kfree(chip);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1024)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1025) We didn't implement the hardware disabling part in the above. If you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1026) need to do this, please note that the destructor may be called even
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1027) before the initialization of the chip is completed. It would be better
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1028) to have a flag to skip hardware disabling if the hardware was not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1029) initialized yet.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1030)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1031) When the chip-data is assigned to the card using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1032) :c:func:`snd_device_new()` with ``SNDRV_DEV_LOWLELVEL`` , its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1033) destructor is called at the last. That is, it is assured that all other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1034) components like PCMs and controls have already been released. You don't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1035) have to stop PCMs, etc. explicitly, but just call low-level hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1036) stopping.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1037)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1038) The management of a memory-mapped region is almost as same as the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1039) management of an I/O port. You'll need three fields like the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1040) following:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1041)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1042) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1043)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1044) struct mychip {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1045) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1046) unsigned long iobase_phys;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1047) void __iomem *iobase_virt;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1048) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1049)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1050) and the allocation would be like below:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1051)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1052) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1053)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1054) err = pci_request_regions(pci, "My Chip");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1055) if (err < 0) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1056) kfree(chip);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1057) return err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1058) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1059) chip->iobase_phys = pci_resource_start(pci, 0);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1060) chip->iobase_virt = ioremap(chip->iobase_phys,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1061) pci_resource_len(pci, 0));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1062)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1063) and the corresponding destructor would be:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1064)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1065) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1066)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1067) static int snd_mychip_free(struct mychip *chip)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1068) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1069) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1070) if (chip->iobase_virt)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1071) iounmap(chip->iobase_virt);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1072) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1073) pci_release_regions(chip->pci);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1074) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1075) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1076)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1077) Of course, a modern way with :c:func:`pci_iomap()` will make things a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1078) bit easier, too.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1079)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1080) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1081)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1082) err = pci_request_regions(pci, "My Chip");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1083) if (err < 0) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1084) kfree(chip);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1085) return err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1086) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1087) chip->iobase_virt = pci_iomap(pci, 0, 0);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1088)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1089) which is paired with :c:func:`pci_iounmap()` at destructor.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1090)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1091)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1092) PCI Entries
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1093) -----------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1094)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1095) So far, so good. Let's finish the missing PCI stuff. At first, we need a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1096) struct pci_device_id table for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1097) this chipset. It's a table of PCI vendor/device ID number, and some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1098) masks.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1099)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1100) For example,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1101)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1102) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1103)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1104) static struct pci_device_id snd_mychip_ids[] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1105) { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1106) PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, },
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1107) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1108) { 0, }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1109) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1110) MODULE_DEVICE_TABLE(pci, snd_mychip_ids);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1112) The first and second fields of the struct pci_device_id are the vendor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1113) and device IDs. If you have no reason to filter the matching devices, you can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1114) leave the remaining fields as above. The last field of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1115) struct pci_device_id contains private data for this entry. You can specify
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1116) any value here, for example, to define specific operations for supported
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1117) device IDs. Such an example is found in the intel8x0 driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1119) The last entry of this list is the terminator. You must specify this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1120) all-zero entry.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1122) Then, prepare the struct pci_driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1123) record:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1124)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1125) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1126)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1127) static struct pci_driver driver = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1128) .name = KBUILD_MODNAME,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1129) .id_table = snd_mychip_ids,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1130) .probe = snd_mychip_probe,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1131) .remove = snd_mychip_remove,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1132) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1133)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1134) The ``probe`` and ``remove`` functions have already been defined in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1135) the previous sections. The ``name`` field is the name string of this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1136) device. Note that you must not use a slash “/” in this string.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1137)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1138) And at last, the module entries:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1139)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1140) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1141)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1142) static int __init alsa_card_mychip_init(void)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1143) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1144) return pci_register_driver(&driver);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1145) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1146)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1147) static void __exit alsa_card_mychip_exit(void)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1148) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1149) pci_unregister_driver(&driver);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1150) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1151)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1152) module_init(alsa_card_mychip_init)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1153) module_exit(alsa_card_mychip_exit)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1154)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1155) Note that these module entries are tagged with ``__init`` and ``__exit``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1156) prefixes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1157)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1158) That's all!
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1159)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1160) PCM Interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1161) =============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1162)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1163) General
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1164) -------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1165)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1166) The PCM middle layer of ALSA is quite powerful and it is only necessary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1167) for each driver to implement the low-level functions to access its
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1168) hardware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1169)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1170) For accessing to the PCM layer, you need to include ``<sound/pcm.h>``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1171) first. In addition, ``<sound/pcm_params.h>`` might be needed if you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1172) access to some functions related with hw_param.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1173)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1174) Each card device can have up to four pcm instances. A pcm instance
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1175) corresponds to a pcm device file. The limitation of number of instances
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1176) comes only from the available bit size of the Linux's device numbers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1177) Once when 64bit device number is used, we'll have more pcm instances
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1178) available.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1179)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1180) A pcm instance consists of pcm playback and capture streams, and each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1181) pcm stream consists of one or more pcm substreams. Some soundcards
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1182) support multiple playback functions. For example, emu10k1 has a PCM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1183) playback of 32 stereo substreams. In this case, at each open, a free
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1184) substream is (usually) automatically chosen and opened. Meanwhile, when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1185) only one substream exists and it was already opened, the successful open
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1186) will either block or error with ``EAGAIN`` according to the file open
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1187) mode. But you don't have to care about such details in your driver. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1188) PCM middle layer will take care of such work.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1189)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1190) Full Code Example
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1191) -----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1192)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1193) The example code below does not include any hardware access routines but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1194) shows only the skeleton, how to build up the PCM interfaces.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1195)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1196) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1197)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1198) #include <sound/pcm.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1199) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1200)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1201) /* hardware definition */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1202) static struct snd_pcm_hardware snd_mychip_playback_hw = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1203) .info = (SNDRV_PCM_INFO_MMAP |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1204) SNDRV_PCM_INFO_INTERLEAVED |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1205) SNDRV_PCM_INFO_BLOCK_TRANSFER |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1206) SNDRV_PCM_INFO_MMAP_VALID),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1207) .formats = SNDRV_PCM_FMTBIT_S16_LE,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1208) .rates = SNDRV_PCM_RATE_8000_48000,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1209) .rate_min = 8000,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1210) .rate_max = 48000,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1211) .channels_min = 2,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1212) .channels_max = 2,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1213) .buffer_bytes_max = 32768,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1214) .period_bytes_min = 4096,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1215) .period_bytes_max = 32768,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1216) .periods_min = 1,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1217) .periods_max = 1024,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1218) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1219)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1220) /* hardware definition */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1221) static struct snd_pcm_hardware snd_mychip_capture_hw = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1222) .info = (SNDRV_PCM_INFO_MMAP |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1223) SNDRV_PCM_INFO_INTERLEAVED |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1224) SNDRV_PCM_INFO_BLOCK_TRANSFER |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1225) SNDRV_PCM_INFO_MMAP_VALID),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1226) .formats = SNDRV_PCM_FMTBIT_S16_LE,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1227) .rates = SNDRV_PCM_RATE_8000_48000,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1228) .rate_min = 8000,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1229) .rate_max = 48000,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1230) .channels_min = 2,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1231) .channels_max = 2,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1232) .buffer_bytes_max = 32768,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1233) .period_bytes_min = 4096,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1234) .period_bytes_max = 32768,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1235) .periods_min = 1,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1236) .periods_max = 1024,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1237) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1238)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1239) /* open callback */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1240) static int snd_mychip_playback_open(struct snd_pcm_substream *substream)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1241) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1242) struct mychip *chip = snd_pcm_substream_chip(substream);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1243) struct snd_pcm_runtime *runtime = substream->runtime;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1244)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1245) runtime->hw = snd_mychip_playback_hw;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1246) /* more hardware-initialization will be done here */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1247) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1248) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1249) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1250)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1251) /* close callback */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1252) static int snd_mychip_playback_close(struct snd_pcm_substream *substream)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1253) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1254) struct mychip *chip = snd_pcm_substream_chip(substream);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1255) /* the hardware-specific codes will be here */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1256) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1257) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1258)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1259) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1260)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1261) /* open callback */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1262) static int snd_mychip_capture_open(struct snd_pcm_substream *substream)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1263) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1264) struct mychip *chip = snd_pcm_substream_chip(substream);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1265) struct snd_pcm_runtime *runtime = substream->runtime;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1266)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1267) runtime->hw = snd_mychip_capture_hw;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1268) /* more hardware-initialization will be done here */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1269) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1270) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1271) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1272)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1273) /* close callback */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1274) static int snd_mychip_capture_close(struct snd_pcm_substream *substream)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1275) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1276) struct mychip *chip = snd_pcm_substream_chip(substream);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1277) /* the hardware-specific codes will be here */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1278) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1279) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1280) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1281)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1282) /* hw_params callback */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1283) static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1284) struct snd_pcm_hw_params *hw_params)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1285) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1286) /* the hardware-specific codes will be here */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1287) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1288) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1289) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1290)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1291) /* hw_free callback */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1292) static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1293) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1294) /* the hardware-specific codes will be here */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1295) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1296) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1297) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1298)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1299) /* prepare callback */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1300) static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1301) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1302) struct mychip *chip = snd_pcm_substream_chip(substream);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1303) struct snd_pcm_runtime *runtime = substream->runtime;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1304)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1305) /* set up the hardware with the current configuration
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1306) * for example...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1307) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1308) mychip_set_sample_format(chip, runtime->format);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1309) mychip_set_sample_rate(chip, runtime->rate);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1310) mychip_set_channels(chip, runtime->channels);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1311) mychip_set_dma_setup(chip, runtime->dma_addr,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1312) chip->buffer_size,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1313) chip->period_size);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1314) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1315) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1316)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1317) /* trigger callback */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1318) static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1319) int cmd)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1320) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1321) switch (cmd) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1322) case SNDRV_PCM_TRIGGER_START:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1323) /* do something to start the PCM engine */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1324) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1325) break;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1326) case SNDRV_PCM_TRIGGER_STOP:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1327) /* do something to stop the PCM engine */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1328) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1329) break;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1330) default:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1331) return -EINVAL;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1332) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1333) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1334)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1335) /* pointer callback */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1336) static snd_pcm_uframes_t
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1337) snd_mychip_pcm_pointer(struct snd_pcm_substream *substream)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1338) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1339) struct mychip *chip = snd_pcm_substream_chip(substream);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1340) unsigned int current_ptr;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1341)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1342) /* get the current hardware pointer */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1343) current_ptr = mychip_get_hw_pointer(chip);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1344) return current_ptr;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1345) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1346)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1347) /* operators */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1348) static struct snd_pcm_ops snd_mychip_playback_ops = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1349) .open = snd_mychip_playback_open,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1350) .close = snd_mychip_playback_close,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1351) .hw_params = snd_mychip_pcm_hw_params,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1352) .hw_free = snd_mychip_pcm_hw_free,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1353) .prepare = snd_mychip_pcm_prepare,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1354) .trigger = snd_mychip_pcm_trigger,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1355) .pointer = snd_mychip_pcm_pointer,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1356) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1357)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1358) /* operators */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1359) static struct snd_pcm_ops snd_mychip_capture_ops = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1360) .open = snd_mychip_capture_open,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1361) .close = snd_mychip_capture_close,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1362) .hw_params = snd_mychip_pcm_hw_params,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1363) .hw_free = snd_mychip_pcm_hw_free,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1364) .prepare = snd_mychip_pcm_prepare,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1365) .trigger = snd_mychip_pcm_trigger,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1366) .pointer = snd_mychip_pcm_pointer,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1367) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1368)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1369) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1370) * definitions of capture are omitted here...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1371) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1372)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1373) /* create a pcm device */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1374) static int snd_mychip_new_pcm(struct mychip *chip)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1375) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1376) struct snd_pcm *pcm;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1377) int err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1378)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1379) err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1380) if (err < 0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1381) return err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1382) pcm->private_data = chip;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1383) strcpy(pcm->name, "My Chip");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1384) chip->pcm = pcm;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1385) /* set operators */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1386) snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1387) &snd_mychip_playback_ops);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1388) snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1389) &snd_mychip_capture_ops);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1390) /* pre-allocation of buffers */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1391) /* NOTE: this may fail */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1392) snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1393) &chip->pci->dev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1394) 64*1024, 64*1024);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1395) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1396) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1397)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1398)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1399) PCM Constructor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1400) ---------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1401)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1402) A pcm instance is allocated by the :c:func:`snd_pcm_new()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1403) function. It would be better to create a constructor for pcm, namely,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1404)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1405) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1406)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1407) static int snd_mychip_new_pcm(struct mychip *chip)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1408) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1409) struct snd_pcm *pcm;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1410) int err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1411)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1412) err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1413) if (err < 0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1414) return err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1415) pcm->private_data = chip;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1416) strcpy(pcm->name, "My Chip");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1417) chip->pcm = pcm;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1418) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1419) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1420) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1421)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1422) The :c:func:`snd_pcm_new()` function takes four arguments. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1423) first argument is the card pointer to which this pcm is assigned, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1424) the second is the ID string.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1425)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1426) The third argument (``index``, 0 in the above) is the index of this new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1427) pcm. It begins from zero. If you create more than one pcm instances,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1428) specify the different numbers in this argument. For example, ``index =
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1429) 1`` for the second PCM device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1430)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1431) The fourth and fifth arguments are the number of substreams for playback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1432) and capture, respectively. Here 1 is used for both arguments. When no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1433) playback or capture substreams are available, pass 0 to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1434) corresponding argument.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1435)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1436) If a chip supports multiple playbacks or captures, you can specify more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1437) numbers, but they must be handled properly in open/close, etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1438) callbacks. When you need to know which substream you are referring to,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1439) then it can be obtained from struct snd_pcm_substream data passed to each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1440) callback as follows:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1441)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1442) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1443)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1444) struct snd_pcm_substream *substream;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1445) int index = substream->number;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1446)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1447)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1448) After the pcm is created, you need to set operators for each pcm stream.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1449)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1450) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1451)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1452) snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1453) &snd_mychip_playback_ops);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1454) snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1455) &snd_mychip_capture_ops);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1456)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1457) The operators are defined typically like this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1458)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1459) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1460)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1461) static struct snd_pcm_ops snd_mychip_playback_ops = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1462) .open = snd_mychip_pcm_open,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1463) .close = snd_mychip_pcm_close,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1464) .hw_params = snd_mychip_pcm_hw_params,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1465) .hw_free = snd_mychip_pcm_hw_free,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1466) .prepare = snd_mychip_pcm_prepare,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1467) .trigger = snd_mychip_pcm_trigger,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1468) .pointer = snd_mychip_pcm_pointer,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1469) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1470)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1471) All the callbacks are described in the Operators_ subsection.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1472)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1473) After setting the operators, you probably will want to pre-allocate the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1474) buffer and set up the managed allocation mode.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1475) For that, simply call the following:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1476)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1477) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1478)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1479) snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1480) &chip->pci->dev,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1481) 64*1024, 64*1024);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1482)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1483) It will allocate a buffer up to 64kB as default. Buffer management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1484) details will be described in the later section `Buffer and Memory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1485) Management`_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1486)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1487) Additionally, you can set some extra information for this pcm in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1488) ``pcm->info_flags``. The available values are defined as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1489) ``SNDRV_PCM_INFO_XXX`` in ``<sound/asound.h>``, which is used for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1490) hardware definition (described later). When your soundchip supports only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1491) half-duplex, specify like this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1492)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1493) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1494)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1495) pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1496)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1497)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1498) ... And the Destructor?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1499) -----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1500)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1501) The destructor for a pcm instance is not always necessary. Since the pcm
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1502) device will be released by the middle layer code automatically, you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1503) don't have to call the destructor explicitly.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1504)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1505) The destructor would be necessary if you created special records
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1506) internally and needed to release them. In such a case, set the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1507) destructor function to ``pcm->private_free``:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1508)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1509) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1510)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1511) static void mychip_pcm_free(struct snd_pcm *pcm)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1512) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1513) struct mychip *chip = snd_pcm_chip(pcm);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1514) /* free your own data */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1515) kfree(chip->my_private_pcm_data);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1516) /* do what you like else */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1517) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1518) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1519)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1520) static int snd_mychip_new_pcm(struct mychip *chip)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1521) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1522) struct snd_pcm *pcm;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1523) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1524) /* allocate your own data */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1525) chip->my_private_pcm_data = kmalloc(...);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1526) /* set the destructor */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1527) pcm->private_data = chip;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1528) pcm->private_free = mychip_pcm_free;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1529) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1530) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1531)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1532)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1533)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1534) Runtime Pointer - The Chest of PCM Information
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1535) ----------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1536)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1537) When the PCM substream is opened, a PCM runtime instance is allocated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1538) and assigned to the substream. This pointer is accessible via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1539) ``substream->runtime``. This runtime pointer holds most information you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1540) need to control the PCM: the copy of hw_params and sw_params
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1541) configurations, the buffer pointers, mmap records, spinlocks, etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1542)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1543) The definition of runtime instance is found in ``<sound/pcm.h>``. Here
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1544) are the contents of this file:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1545)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1546) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1547)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1548) struct _snd_pcm_runtime {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1549) /* -- Status -- */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1550) struct snd_pcm_substream *trigger_master;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1551) snd_timestamp_t trigger_tstamp; /* trigger timestamp */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1552) int overrange;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1553) snd_pcm_uframes_t avail_max;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1554) snd_pcm_uframes_t hw_ptr_base; /* Position at buffer restart */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1555) snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1556)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1557) /* -- HW params -- */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1558) snd_pcm_access_t access; /* access mode */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1559) snd_pcm_format_t format; /* SNDRV_PCM_FORMAT_* */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1560) snd_pcm_subformat_t subformat; /* subformat */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1561) unsigned int rate; /* rate in Hz */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1562) unsigned int channels; /* channels */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1563) snd_pcm_uframes_t period_size; /* period size */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1564) unsigned int periods; /* periods */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1565) snd_pcm_uframes_t buffer_size; /* buffer size */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1566) unsigned int tick_time; /* tick time */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1567) snd_pcm_uframes_t min_align; /* Min alignment for the format */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1568) size_t byte_align;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1569) unsigned int frame_bits;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1570) unsigned int sample_bits;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1571) unsigned int info;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1572) unsigned int rate_num;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1573) unsigned int rate_den;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1574)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1575) /* -- SW params -- */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1576) struct timespec tstamp_mode; /* mmap timestamp is updated */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1577) unsigned int period_step;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1578) unsigned int sleep_min; /* min ticks to sleep */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1579) snd_pcm_uframes_t start_threshold;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1580) snd_pcm_uframes_t stop_threshold;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1581) snd_pcm_uframes_t silence_threshold; /* Silence filling happens when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1582) noise is nearest than this */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1583) snd_pcm_uframes_t silence_size; /* Silence filling size */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1584) snd_pcm_uframes_t boundary; /* pointers wrap point */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1585)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1586) snd_pcm_uframes_t silenced_start;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1587) snd_pcm_uframes_t silenced_size;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1588)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1589) snd_pcm_sync_id_t sync; /* hardware synchronization ID */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1590)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1591) /* -- mmap -- */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1592) volatile struct snd_pcm_mmap_status *status;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1593) volatile struct snd_pcm_mmap_control *control;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1594) atomic_t mmap_count;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1595)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1596) /* -- locking / scheduling -- */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1597) spinlock_t lock;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1598) wait_queue_head_t sleep;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1599) struct timer_list tick_timer;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1600) struct fasync_struct *fasync;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1601)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1602) /* -- private section -- */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1603) void *private_data;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1604) void (*private_free)(struct snd_pcm_runtime *runtime);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1605)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1606) /* -- hardware description -- */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1607) struct snd_pcm_hardware hw;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1608) struct snd_pcm_hw_constraints hw_constraints;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1609)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1610) /* -- timer -- */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1611) unsigned int timer_resolution; /* timer resolution */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1612)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1613) /* -- DMA -- */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1614) unsigned char *dma_area; /* DMA area */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1615) dma_addr_t dma_addr; /* physical bus address (not accessible from main CPU) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1616) size_t dma_bytes; /* size of DMA area */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1617)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1618) struct snd_dma_buffer *dma_buffer_p; /* allocated buffer */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1619)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1620) #if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1621) /* -- OSS things -- */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1622) struct snd_pcm_oss_runtime oss;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1623) #endif
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1624) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1625)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1626)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1627) For the operators (callbacks) of each sound driver, most of these
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1628) records are supposed to be read-only. Only the PCM middle-layer changes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1629) / updates them. The exceptions are the hardware description (hw) DMA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1630) buffer information and the private data. Besides, if you use the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1631) standard managed buffer allocation mode, you don't need to set the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1632) DMA buffer information by yourself.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1633)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1634) In the sections below, important records are explained.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1635)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1636) Hardware Description
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1637) ~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1638)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1639) The hardware descriptor (struct snd_pcm_hardware) contains the definitions of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1640) the fundamental hardware configuration. Above all, you'll need to define this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1641) in the `PCM open callback`_. Note that the runtime instance holds the copy of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1642) the descriptor, not the pointer to the existing descriptor. That is,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1643) in the open callback, you can modify the copied descriptor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1644) (``runtime->hw``) as you need. For example, if the maximum number of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1645) channels is 1 only on some chip models, you can still use the same
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1646) hardware descriptor and change the channels_max later:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1647)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1648) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1649)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1650) struct snd_pcm_runtime *runtime = substream->runtime;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1651) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1652) runtime->hw = snd_mychip_playback_hw; /* common definition */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1653) if (chip->model == VERY_OLD_ONE)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1654) runtime->hw.channels_max = 1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1655)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1656) Typically, you'll have a hardware descriptor as below:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1657)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1658) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1659)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1660) static struct snd_pcm_hardware snd_mychip_playback_hw = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1661) .info = (SNDRV_PCM_INFO_MMAP |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1662) SNDRV_PCM_INFO_INTERLEAVED |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1663) SNDRV_PCM_INFO_BLOCK_TRANSFER |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1664) SNDRV_PCM_INFO_MMAP_VALID),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1665) .formats = SNDRV_PCM_FMTBIT_S16_LE,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1666) .rates = SNDRV_PCM_RATE_8000_48000,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1667) .rate_min = 8000,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1668) .rate_max = 48000,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1669) .channels_min = 2,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1670) .channels_max = 2,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1671) .buffer_bytes_max = 32768,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1672) .period_bytes_min = 4096,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1673) .period_bytes_max = 32768,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1674) .periods_min = 1,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1675) .periods_max = 1024,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1676) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1677)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1678) - The ``info`` field contains the type and capabilities of this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1679) pcm. The bit flags are defined in ``<sound/asound.h>`` as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1680) ``SNDRV_PCM_INFO_XXX``. Here, at least, you have to specify whether
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1681) the mmap is supported and which interleaved format is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1682) supported. When the hardware supports mmap, add the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1683) ``SNDRV_PCM_INFO_MMAP`` flag here. When the hardware supports the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1684) interleaved or the non-interleaved formats,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1685) ``SNDRV_PCM_INFO_INTERLEAVED`` or ``SNDRV_PCM_INFO_NONINTERLEAVED``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1686) flag must be set, respectively. If both are supported, you can set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1687) both, too.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1688)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1689) In the above example, ``MMAP_VALID`` and ``BLOCK_TRANSFER`` are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1690) specified for the OSS mmap mode. Usually both are set. Of course,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1691) ``MMAP_VALID`` is set only if the mmap is really supported.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1692)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1693) The other possible flags are ``SNDRV_PCM_INFO_PAUSE`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1694) ``SNDRV_PCM_INFO_RESUME``. The ``PAUSE`` bit means that the pcm
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1695) supports the “pause” operation, while the ``RESUME`` bit means that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1696) the pcm supports the full “suspend/resume” operation. If the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1697) ``PAUSE`` flag is set, the ``trigger`` callback below must handle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1698) the corresponding (pause push/release) commands. The suspend/resume
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1699) trigger commands can be defined even without the ``RESUME``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1700) flag. See `Power Management`_ section for details.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1701)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1702) When the PCM substreams can be synchronized (typically,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1703) synchronized start/stop of a playback and a capture streams), you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1704) can give ``SNDRV_PCM_INFO_SYNC_START``, too. In this case, you'll
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1705) need to check the linked-list of PCM substreams in the trigger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1706) callback. This will be described in the later section.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1707)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1708) - ``formats`` field contains the bit-flags of supported formats
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1709) (``SNDRV_PCM_FMTBIT_XXX``). If the hardware supports more than one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1710) format, give all or'ed bits. In the example above, the signed 16bit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1711) little-endian format is specified.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1712)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1713) - ``rates`` field contains the bit-flags of supported rates
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1714) (``SNDRV_PCM_RATE_XXX``). When the chip supports continuous rates,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1715) pass ``CONTINUOUS`` bit additionally. The pre-defined rate bits are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1716) provided only for typical rates. If your chip supports
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1717) unconventional rates, you need to add the ``KNOT`` bit and set up
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1718) the hardware constraint manually (explained later).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1719)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1720) - ``rate_min`` and ``rate_max`` define the minimum and maximum sample
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1721) rate. This should correspond somehow to ``rates`` bits.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1722)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1723) - ``channel_min`` and ``channel_max`` define, as you might already
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1724) expected, the minimum and maximum number of channels.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1725)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1726) - ``buffer_bytes_max`` defines the maximum buffer size in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1727) bytes. There is no ``buffer_bytes_min`` field, since it can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1728) calculated from the minimum period size and the minimum number of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1729) periods. Meanwhile, ``period_bytes_min`` and define the minimum and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1730) maximum size of the period in bytes. ``periods_max`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1731) ``periods_min`` define the maximum and minimum number of periods in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1732) the buffer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1733)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1734) The “period” is a term that corresponds to a fragment in the OSS
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1735) world. The period defines the size at which a PCM interrupt is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1736) generated. This size strongly depends on the hardware. Generally,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1737) the smaller period size will give you more interrupts, that is,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1738) more controls. In the case of capture, this size defines the input
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1739) latency. On the other hand, the whole buffer size defines the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1740) output latency for the playback direction.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1741)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1742) - There is also a field ``fifo_size``. This specifies the size of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1743) hardware FIFO, but currently it is neither used in the driver nor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1744) in the alsa-lib. So, you can ignore this field.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1745)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1746) PCM Configurations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1747) ~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1748)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1749) Ok, let's go back again to the PCM runtime records. The most
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1750) frequently referred records in the runtime instance are the PCM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1751) configurations. The PCM configurations are stored in the runtime
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1752) instance after the application sends ``hw_params`` data via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1753) alsa-lib. There are many fields copied from hw_params and sw_params
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1754) structs. For example, ``format`` holds the format type chosen by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1755) application. This field contains the enum value
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1756) ``SNDRV_PCM_FORMAT_XXX``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1757)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1758) One thing to be noted is that the configured buffer and period sizes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1759) are stored in “frames” in the runtime. In the ALSA world, ``1 frame =
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1760) channels \* samples-size``. For conversion between frames and bytes,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1761) you can use the :c:func:`frames_to_bytes()` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1762) :c:func:`bytes_to_frames()` helper functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1763)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1764) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1765)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1766) period_bytes = frames_to_bytes(runtime, runtime->period_size);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1767)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1768) Also, many software parameters (sw_params) are stored in frames, too.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1769) Please check the type of the field. ``snd_pcm_uframes_t`` is for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1770) frames as unsigned integer while ``snd_pcm_sframes_t`` is for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1771) frames as signed integer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1772)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1773) DMA Buffer Information
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1774) ~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1775)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1776) The DMA buffer is defined by the following four fields, ``dma_area``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1777) ``dma_addr``, ``dma_bytes`` and ``dma_private``. The ``dma_area``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1778) holds the buffer pointer (the logical address). You can call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1779) :c:func:`memcpy()` from/to this pointer. Meanwhile, ``dma_addr`` holds
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1780) the physical address of the buffer. This field is specified only when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1781) the buffer is a linear buffer. ``dma_bytes`` holds the size of buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1782) in bytes. ``dma_private`` is used for the ALSA DMA allocator.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1783)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1784) If you use either the managed buffer allocation mode or the standard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1785) API function :c:func:`snd_pcm_lib_malloc_pages()` for allocating the buffer,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1786) these fields are set by the ALSA middle layer, and you should *not*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1787) change them by yourself. You can read them but not write them. On the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1788) other hand, if you want to allocate the buffer by yourself, you'll
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1789) need to manage it in hw_params callback. At least, ``dma_bytes`` is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1790) mandatory. ``dma_area`` is necessary when the buffer is mmapped. If
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1791) your driver doesn't support mmap, this field is not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1792) necessary. ``dma_addr`` is also optional. You can use dma_private as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1793) you like, too.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1794)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1795) Running Status
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1796) ~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1797)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1798) The running status can be referred via ``runtime->status``. This is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1799) the pointer to the struct snd_pcm_mmap_status record.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1800) For example, you can get the current
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1801) DMA hardware pointer via ``runtime->status->hw_ptr``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1802)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1803) The DMA application pointer can be referred via ``runtime->control``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1804) which points to the struct snd_pcm_mmap_control record.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1805) However, accessing directly to this value is not recommended.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1806)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1807) Private Data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1808) ~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1809)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1810) You can allocate a record for the substream and store it in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1811) ``runtime->private_data``. Usually, this is done in the `PCM open
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1812) callback`_. Don't mix this with ``pcm->private_data``. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1813) ``pcm->private_data`` usually points to the chip instance assigned
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1814) statically at the creation of PCM, while the ``runtime->private_data``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1815) points to a dynamic data structure created at the PCM open
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1816) callback.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1817)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1818) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1819)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1820) static int snd_xxx_open(struct snd_pcm_substream *substream)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1821) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1822) struct my_pcm_data *data;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1823) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1824) data = kmalloc(sizeof(*data), GFP_KERNEL);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1825) substream->runtime->private_data = data;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1826) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1827) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1828)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1829)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1830) The allocated object must be released in the `close callback`_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1831)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1832) Operators
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1833) ---------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1834)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1835) OK, now let me give details about each pcm callback (``ops``). In
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1836) general, every callback must return 0 if successful, or a negative
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1837) error number such as ``-EINVAL``. To choose an appropriate error
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1838) number, it is advised to check what value other parts of the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1839) return when the same kind of request fails.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1840)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1841) The callback function takes at least the argument with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1842) struct snd_pcm_substream pointer. To retrieve the chip
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1843) record from the given substream instance, you can use the following
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1844) macro.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1845)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1846) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1847)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1848) int xxx() {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1849) struct mychip *chip = snd_pcm_substream_chip(substream);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1850) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1851) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1852)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1853) The macro reads ``substream->private_data``, which is a copy of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1854) ``pcm->private_data``. You can override the former if you need to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1855) assign different data records per PCM substream. For example, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1856) cmi8330 driver assigns different ``private_data`` for playback and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1857) capture directions, because it uses two different codecs (SB- and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1858) AD-compatible) for different directions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1859)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1860) PCM open callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1861) ~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1862)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1863) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1864)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1865) static int snd_xxx_open(struct snd_pcm_substream *substream);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1866)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1867) This is called when a pcm substream is opened.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1868)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1869) At least, here you have to initialize the ``runtime->hw``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1870) record. Typically, this is done by like this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1871)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1872) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1873)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1874) static int snd_xxx_open(struct snd_pcm_substream *substream)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1875) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1876) struct mychip *chip = snd_pcm_substream_chip(substream);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1877) struct snd_pcm_runtime *runtime = substream->runtime;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1878)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1879) runtime->hw = snd_mychip_playback_hw;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1880) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1881) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1882)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1883) where ``snd_mychip_playback_hw`` is the pre-defined hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1884) description.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1885)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1886) You can allocate a private data in this callback, as described in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1887) `Private Data`_ section.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1888)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1889) If the hardware configuration needs more constraints, set the hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1890) constraints here, too. See Constraints_ for more details.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1891)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1892) close callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1893) ~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1894)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1895) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1896)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1897) static int snd_xxx_close(struct snd_pcm_substream *substream);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1898)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1899)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1900) Obviously, this is called when a pcm substream is closed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1901)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1902) Any private instance for a pcm substream allocated in the ``open``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1903) callback will be released here.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1904)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1905) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1906)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1907) static int snd_xxx_close(struct snd_pcm_substream *substream)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1908) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1909) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1910) kfree(substream->runtime->private_data);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1911) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1912) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1913)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1914) ioctl callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1915) ~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1916)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1917) This is used for any special call to pcm ioctls. But usually you can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1918) leave it as NULL, then PCM core calls the generic ioctl callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1919) function :c:func:`snd_pcm_lib_ioctl()`. If you need to deal with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1920) unique setup of channel info or reset procedure, you can pass your own
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1921) callback function here.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1922)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1923) hw_params callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1924) ~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1925)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1926) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1927)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1928) static int snd_xxx_hw_params(struct snd_pcm_substream *substream,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1929) struct snd_pcm_hw_params *hw_params);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1930)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1931) This is called when the hardware parameter (``hw_params``) is set up
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1932) by the application, that is, once when the buffer size, the period
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1933) size, the format, etc. are defined for the pcm substream.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1934)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1935) Many hardware setups should be done in this callback, including the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1936) allocation of buffers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1937)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1938) Parameters to be initialized are retrieved by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1939) :c:func:`params_xxx()` macros.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1940)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1941) When you set up the managed buffer allocation mode for the substream,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1942) a buffer is already allocated before this callback gets
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1943) called. Alternatively, you can call a helper function below for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1944) allocating the buffer, too.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1945)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1946) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1947)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1948) snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1949)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1950) :c:func:`snd_pcm_lib_malloc_pages()` is available only when the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1951) DMA buffers have been pre-allocated. See the section `Buffer Types`_
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1952) for more details.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1953)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1954) Note that this and ``prepare`` callbacks may be called multiple times
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1955) per initialization. For example, the OSS emulation may call these
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1956) callbacks at each change via its ioctl.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1957)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1958) Thus, you need to be careful not to allocate the same buffers many
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1959) times, which will lead to memory leaks! Calling the helper function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1960) above many times is OK. It will release the previous buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1961) automatically when it was already allocated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1962)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1963) Another note is that this callback is non-atomic (schedulable) as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1964) default, i.e. when no ``nonatomic`` flag set. This is important,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1965) because the ``trigger`` callback is atomic (non-schedulable). That is,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1966) mutexes or any schedule-related functions are not available in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1967) ``trigger`` callback. Please see the subsection Atomicity_ for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1968) details.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1969)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1970) hw_free callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1971) ~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1972)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1973) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1974)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1975) static int snd_xxx_hw_free(struct snd_pcm_substream *substream);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1976)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1977) This is called to release the resources allocated via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1978) ``hw_params``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1979)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1980) This function is always called before the close callback is called.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1981) Also, the callback may be called multiple times, too. Keep track
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1982) whether the resource was already released.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1983)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1984) When you have set up the managed buffer allocation mode for the PCM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1985) substream, the allocated PCM buffer will be automatically released
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1986) after this callback gets called. Otherwise you'll have to release the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1987) buffer manually. Typically, when the buffer was allocated from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1988) pre-allocated pool, you can use the standard API function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1989) :c:func:`snd_pcm_lib_malloc_pages()` like:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1990)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1991) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1992)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1993) snd_pcm_lib_free_pages(substream);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1994)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1995) prepare callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1996) ~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1997)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1998) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1999)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2000) static int snd_xxx_prepare(struct snd_pcm_substream *substream);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2001)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2002) This callback is called when the pcm is “prepared”. You can set the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2003) format type, sample rate, etc. here. The difference from ``hw_params``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2004) is that the ``prepare`` callback will be called each time
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2005) :c:func:`snd_pcm_prepare()` is called, i.e. when recovering after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2006) underruns, etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2007)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2008) Note that this callback is now non-atomic. You can use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2009) schedule-related functions safely in this callback.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2010)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2011) In this and the following callbacks, you can refer to the values via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2012) the runtime record, ``substream->runtime``. For example, to get the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2013) current rate, format or channels, access to ``runtime->rate``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2014) ``runtime->format`` or ``runtime->channels``, respectively. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2015) physical address of the allocated buffer is set to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2016) ``runtime->dma_area``. The buffer and period sizes are in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2017) ``runtime->buffer_size`` and ``runtime->period_size``, respectively.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2018)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2019) Be careful that this callback will be called many times at each setup,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2020) too.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2021)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2022) trigger callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2023) ~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2024)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2025) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2026)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2027) static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2028)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2029) This is called when the pcm is started, stopped or paused.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2030)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2031) Which action is specified in the second argument,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2032) ``SNDRV_PCM_TRIGGER_XXX`` in ``<sound/pcm.h>``. At least, the ``START``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2033) and ``STOP`` commands must be defined in this callback.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2034)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2035) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2036)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2037) switch (cmd) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2038) case SNDRV_PCM_TRIGGER_START:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2039) /* do something to start the PCM engine */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2040) break;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2041) case SNDRV_PCM_TRIGGER_STOP:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2042) /* do something to stop the PCM engine */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2043) break;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2044) default:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2045) return -EINVAL;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2046) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2047)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2048) When the pcm supports the pause operation (given in the info field of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2049) the hardware table), the ``PAUSE_PUSH`` and ``PAUSE_RELEASE`` commands
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2050) must be handled here, too. The former is the command to pause the pcm,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2051) and the latter to restart the pcm again.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2052)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2053) When the pcm supports the suspend/resume operation, regardless of full
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2054) or partial suspend/resume support, the ``SUSPEND`` and ``RESUME``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2055) commands must be handled, too. These commands are issued when the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2056) power-management status is changed. Obviously, the ``SUSPEND`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2057) ``RESUME`` commands suspend and resume the pcm substream, and usually,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2058) they are identical to the ``STOP`` and ``START`` commands, respectively.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2059) See the `Power Management`_ section for details.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2060)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2061) As mentioned, this callback is atomic as default unless ``nonatomic``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2062) flag set, and you cannot call functions which may sleep. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2063) ``trigger`` callback should be as minimal as possible, just really
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2064) triggering the DMA. The other stuff should be initialized
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2065) ``hw_params`` and ``prepare`` callbacks properly beforehand.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2066)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2067) sync_stop callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2068) ~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2069)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2070) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2071)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2072) static int snd_xxx_sync_stop(struct snd_pcm_substream *substream);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2073)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2074) This callback is optional, and NULL can be passed. It's called after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2075) the PCM core stops the stream and changes the stream state
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2076) ``prepare``, ``hw_params`` or ``hw_free``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2077) Since the IRQ handler might be still pending, we need to wait until
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2078) the pending task finishes before moving to the next step; otherwise it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2079) might lead to a crash due to resource conflicts or access to the freed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2080) resources. A typical behavior is to call a synchronization function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2081) like :c:func:`synchronize_irq()` here.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2082)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2083) For majority of drivers that need only a call of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2084) :c:func:`synchronize_irq()`, there is a simpler setup, too.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2085) While keeping NULL to ``sync_stop`` PCM callback, the driver can set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2086) ``card->sync_irq`` field to store the valid interrupt number after
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2087) requesting an IRQ, instead. Then PCM core will look call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2088) :c:func:`synchronize_irq()` with the given IRQ appropriately.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2089)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2090) If the IRQ handler is released at the card destructor, you don't need
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2091) to clear ``card->sync_irq``, as the card itself is being released.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2092) So, usually you'll need to add just a single line for assigning
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2093) ``card->sync_irq`` in the driver code unless the driver re-acquires
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2094) the IRQ. When the driver frees and re-acquires the IRQ dynamically
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2095) (e.g. for suspend/resume), it needs to clear and re-set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2096) ``card->sync_irq`` again appropriately.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2097)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2098) pointer callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2099) ~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2101) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2102)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2103) static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2105) This callback is called when the PCM middle layer inquires the current
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2106) hardware position on the buffer. The position must be returned in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2107) frames, ranging from 0 to ``buffer_size - 1``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2109) This is called usually from the buffer-update routine in the pcm
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2110) middle layer, which is invoked when :c:func:`snd_pcm_period_elapsed()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2111) is called in the interrupt routine. Then the pcm middle layer updates
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2112) the position and calculates the available space, and wakes up the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2113) sleeping poll threads, etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2114)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2115) This callback is also atomic as default.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2116)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2117) copy_user, copy_kernel and fill_silence ops
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2118) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2119)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2120) These callbacks are not mandatory, and can be omitted in most cases.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2121) These callbacks are used when the hardware buffer cannot be in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2122) normal memory space. Some chips have their own buffer on the hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2123) which is not mappable. In such a case, you have to transfer the data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2124) manually from the memory buffer to the hardware buffer. Or, if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2125) buffer is non-contiguous on both physical and virtual memory spaces,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2126) these callbacks must be defined, too.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2127)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2128) If these two callbacks are defined, copy and set-silence operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2129) are done by them. The detailed will be described in the later section
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2130) `Buffer and Memory Management`_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2131)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2132) ack callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2133) ~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2134)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2135) This callback is also not mandatory. This callback is called when the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2136) ``appl_ptr`` is updated in read or write operations. Some drivers like
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2137) emu10k1-fx and cs46xx need to track the current ``appl_ptr`` for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2138) internal buffer, and this callback is useful only for such a purpose.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2139)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2140) This callback is atomic as default.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2141)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2142) page callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2143) ~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2144)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2145) This callback is optional too. The mmap calls this callback to get the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2146) page fault address.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2147)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2148) Since the recent changes, you need no special callback any longer for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2149) the standard SG-buffer or vmalloc-buffer. Hence this callback should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2150) be rarely used.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2151)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2152) mmap calllback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2153) ~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2154)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2155) This is another optional callback for controlling mmap behavior.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2156) Once when defined, PCM core calls this callback when a page is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2157) memory-mapped instead of dealing via the standard helper.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2158) If you need special handling (due to some architecture or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2159) device-specific issues), implement everything here as you like.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2160)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2161)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2162) PCM Interrupt Handler
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2163) ---------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2164)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2165) The rest of pcm stuff is the PCM interrupt handler. The role of PCM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2166) interrupt handler in the sound driver is to update the buffer position
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2167) and to tell the PCM middle layer when the buffer position goes across
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2168) the prescribed period size. To inform this, call the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2169) :c:func:`snd_pcm_period_elapsed()` function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2170)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2171) There are several types of sound chips to generate the interrupts.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2172)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2173) Interrupts at the period (fragment) boundary
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2174) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2175)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2176) This is the most frequently found type: the hardware generates an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2177) interrupt at each period boundary. In this case, you can call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2178) :c:func:`snd_pcm_period_elapsed()` at each interrupt.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2179)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2180) :c:func:`snd_pcm_period_elapsed()` takes the substream pointer as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2181) its argument. Thus, you need to keep the substream pointer accessible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2182) from the chip instance. For example, define ``substream`` field in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2183) chip record to hold the current running substream pointer, and set the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2184) pointer value at ``open`` callback (and reset at ``close`` callback).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2185)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2186) If you acquire a spinlock in the interrupt handler, and the lock is used
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2187) in other pcm callbacks, too, then you have to release the lock before
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2188) calling :c:func:`snd_pcm_period_elapsed()`, because
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2189) :c:func:`snd_pcm_period_elapsed()` calls other pcm callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2190) inside.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2191)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2192) Typical code would be like:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2193)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2194) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2195)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2196)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2197) static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2198) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2199) struct mychip *chip = dev_id;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2200) spin_lock(&chip->lock);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2201) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2202) if (pcm_irq_invoked(chip)) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2203) /* call updater, unlock before it */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2204) spin_unlock(&chip->lock);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2205) snd_pcm_period_elapsed(chip->substream);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2206) spin_lock(&chip->lock);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2207) /* acknowledge the interrupt if necessary */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2208) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2209) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2210) spin_unlock(&chip->lock);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2211) return IRQ_HANDLED;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2212) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2213)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2214)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2215)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2216) High frequency timer interrupts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2217) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2218)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2219) This happens when the hardware doesn't generate interrupts at the period
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2220) boundary but issues timer interrupts at a fixed timer rate (e.g. es1968
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2221) or ymfpci drivers). In this case, you need to check the current hardware
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2222) position and accumulate the processed sample length at each interrupt.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2223) When the accumulated size exceeds the period size, call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2224) :c:func:`snd_pcm_period_elapsed()` and reset the accumulator.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2225)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2226) Typical code would be like the following.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2227)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2228) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2229)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2230)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2231) static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2232) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2233) struct mychip *chip = dev_id;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2234) spin_lock(&chip->lock);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2235) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2236) if (pcm_irq_invoked(chip)) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2237) unsigned int last_ptr, size;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2238) /* get the current hardware pointer (in frames) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2239) last_ptr = get_hw_ptr(chip);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2240) /* calculate the processed frames since the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2241) * last update
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2242) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2243) if (last_ptr < chip->last_ptr)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2244) size = runtime->buffer_size + last_ptr
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2245) - chip->last_ptr;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2246) else
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2247) size = last_ptr - chip->last_ptr;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2248) /* remember the last updated point */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2249) chip->last_ptr = last_ptr;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2250) /* accumulate the size */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2251) chip->size += size;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2252) /* over the period boundary? */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2253) if (chip->size >= runtime->period_size) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2254) /* reset the accumulator */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2255) chip->size %= runtime->period_size;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2256) /* call updater */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2257) spin_unlock(&chip->lock);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2258) snd_pcm_period_elapsed(substream);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2259) spin_lock(&chip->lock);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2260) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2261) /* acknowledge the interrupt if necessary */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2262) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2263) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2264) spin_unlock(&chip->lock);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2265) return IRQ_HANDLED;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2266) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2267)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2268)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2269)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2270) On calling :c:func:`snd_pcm_period_elapsed()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2271) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2272)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2273) In both cases, even if more than one period are elapsed, you don't have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2274) to call :c:func:`snd_pcm_period_elapsed()` many times. Call only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2275) once. And the pcm layer will check the current hardware pointer and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2276) update to the latest status.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2277)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2278) Atomicity
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2279) ---------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2280)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2281) One of the most important (and thus difficult to debug) problems in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2282) kernel programming are race conditions. In the Linux kernel, they are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2283) usually avoided via spin-locks, mutexes or semaphores. In general, if a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2284) race condition can happen in an interrupt handler, it has to be managed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2285) atomically, and you have to use a spinlock to protect the critical
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2286) session. If the critical section is not in interrupt handler code and if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2287) taking a relatively long time to execute is acceptable, you should use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2288) mutexes or semaphores instead.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2289)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2290) As already seen, some pcm callbacks are atomic and some are not. For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2291) example, the ``hw_params`` callback is non-atomic, while ``trigger``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2292) callback is atomic. This means, the latter is called already in a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2293) spinlock held by the PCM middle layer. Please take this atomicity into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2294) account when you choose a locking scheme in the callbacks.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2295)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2296) In the atomic callbacks, you cannot use functions which may call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2297) :c:func:`schedule()` or go to :c:func:`sleep()`. Semaphores and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2298) mutexes can sleep, and hence they cannot be used inside the atomic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2299) callbacks (e.g. ``trigger`` callback). To implement some delay in such a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2300) callback, please use :c:func:`udelay()` or :c:func:`mdelay()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2301)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2302) All three atomic callbacks (trigger, pointer, and ack) are called with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2303) local interrupts disabled.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2304)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2305) The recent changes in PCM core code, however, allow all PCM operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2306) to be non-atomic. This assumes that the all caller sides are in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2307) non-atomic contexts. For example, the function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2308) :c:func:`snd_pcm_period_elapsed()` is called typically from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2309) interrupt handler. But, if you set up the driver to use a threaded
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2310) interrupt handler, this call can be in non-atomic context, too. In such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2311) a case, you can set ``nonatomic`` filed of struct snd_pcm object
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2312) after creating it. When this flag is set, mutex and rwsem are used internally
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2313) in the PCM core instead of spin and rwlocks, so that you can call all PCM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2314) functions safely in a non-atomic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2315) context.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2316)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2317) Constraints
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2318) -----------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2319)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2320) If your chip supports unconventional sample rates, or only the limited
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2321) samples, you need to set a constraint for the condition.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2322)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2323) For example, in order to restrict the sample rates in the some supported
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2324) values, use :c:func:`snd_pcm_hw_constraint_list()`. You need to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2325) call this function in the open callback.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2326)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2327) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2328)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2329) static unsigned int rates[] =
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2330) {4000, 10000, 22050, 44100};
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2331) static struct snd_pcm_hw_constraint_list constraints_rates = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2332) .count = ARRAY_SIZE(rates),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2333) .list = rates,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2334) .mask = 0,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2335) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2336)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2337) static int snd_mychip_pcm_open(struct snd_pcm_substream *substream)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2338) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2339) int err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2340) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2341) err = snd_pcm_hw_constraint_list(substream->runtime, 0,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2342) SNDRV_PCM_HW_PARAM_RATE,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2343) &constraints_rates);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2344) if (err < 0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2345) return err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2346) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2347) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2348)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2349)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2350)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2351) There are many different constraints. Look at ``sound/pcm.h`` for a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2352) complete list. You can even define your own constraint rules. For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2353) example, let's suppose my_chip can manage a substream of 1 channel if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2354) and only if the format is ``S16_LE``, otherwise it supports any format
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2355) specified in struct snd_pcm_hardware> (or in any other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2356) constraint_list). You can build a rule like this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2357)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2358) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2359)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2360) static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2361) struct snd_pcm_hw_rule *rule)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2362) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2363) struct snd_interval *c = hw_param_interval(params,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2364) SNDRV_PCM_HW_PARAM_CHANNELS);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2365) struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2366) struct snd_interval ch;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2367)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2368) snd_interval_any(&ch);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2369) if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2370) ch.min = ch.max = 1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2371) ch.integer = 1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2372) return snd_interval_refine(c, &ch);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2373) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2374) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2375) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2376)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2377)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2378) Then you need to call this function to add your rule:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2379)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2380) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2381)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2382) snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2383) hw_rule_channels_by_format, NULL,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2384) SNDRV_PCM_HW_PARAM_FORMAT, -1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2385)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2386) The rule function is called when an application sets the PCM format, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2387) it refines the number of channels accordingly. But an application may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2388) set the number of channels before setting the format. Thus you also need
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2389) to define the inverse rule:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2390)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2391) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2392)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2393) static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2394) struct snd_pcm_hw_rule *rule)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2395) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2396) struct snd_interval *c = hw_param_interval(params,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2397) SNDRV_PCM_HW_PARAM_CHANNELS);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2398) struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2399) struct snd_mask fmt;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2400)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2401) snd_mask_any(&fmt); /* Init the struct */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2402) if (c->min < 2) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2403) fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2404) return snd_mask_refine(f, &fmt);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2405) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2406) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2407) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2408)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2409)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2410) ... and in the open callback:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2411)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2412) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2413)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2414) snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2415) hw_rule_format_by_channels, NULL,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2416) SNDRV_PCM_HW_PARAM_CHANNELS, -1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2417)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2418) One typical usage of the hw constraints is to align the buffer size
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2419) with the period size. As default, ALSA PCM core doesn't enforce the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2420) buffer size to be aligned with the period size. For example, it'd be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2421) possible to have a combination like 256 period bytes with 999 buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2422) bytes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2423)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2424) Many device chips, however, require the buffer to be a multiple of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2425) periods. In such a case, call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2426) :c:func:`snd_pcm_hw_constraint_integer()` for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2427) ``SNDRV_PCM_HW_PARAM_PERIODS``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2428)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2429) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2430)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2431) snd_pcm_hw_constraint_integer(substream->runtime,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2432) SNDRV_PCM_HW_PARAM_PERIODS);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2433)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2434) This assures that the number of periods is integer, hence the buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2435) size is aligned with the period size.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2436)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2437) The hw constraint is a very much powerful mechanism to define the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2438) preferred PCM configuration, and there are relevant helpers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2439) I won't give more details here, rather I would like to say, “Luke, use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2440) the source.”
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2441)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2442) Control Interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2443) =================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2444)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2445) General
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2446) -------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2447)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2448) The control interface is used widely for many switches, sliders, etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2449) which are accessed from user-space. Its most important use is the mixer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2450) interface. In other words, since ALSA 0.9.x, all the mixer stuff is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2451) implemented on the control kernel API.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2452)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2453) ALSA has a well-defined AC97 control module. If your chip supports only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2454) the AC97 and nothing else, you can skip this section.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2455)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2456) The control API is defined in ``<sound/control.h>``. Include this file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2457) if you want to add your own controls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2458)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2459) Definition of Controls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2460) ----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2461)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2462) To create a new control, you need to define the following three
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2463) callbacks: ``info``, ``get`` and ``put``. Then, define a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2464) struct snd_kcontrol_new record, such as:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2465)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2466) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2467)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2468)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2469) static struct snd_kcontrol_new my_control = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2470) .iface = SNDRV_CTL_ELEM_IFACE_MIXER,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2471) .name = "PCM Playback Switch",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2472) .index = 0,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2473) .access = SNDRV_CTL_ELEM_ACCESS_READWRITE,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2474) .private_value = 0xffff,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2475) .info = my_control_info,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2476) .get = my_control_get,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2477) .put = my_control_put
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2478) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2479)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2480)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2481) The ``iface`` field specifies the control type,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2482) ``SNDRV_CTL_ELEM_IFACE_XXX``, which is usually ``MIXER``. Use ``CARD``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2483) for global controls that are not logically part of the mixer. If the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2484) control is closely associated with some specific device on the sound
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2485) card, use ``HWDEP``, ``PCM``, ``RAWMIDI``, ``TIMER``, or ``SEQUENCER``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2486) and specify the device number with the ``device`` and ``subdevice``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2487) fields.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2488)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2489) The ``name`` is the name identifier string. Since ALSA 0.9.x, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2490) control name is very important, because its role is classified from
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2491) its name. There are pre-defined standard control names. The details
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2492) are described in the `Control Names`_ subsection.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2493)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2494) The ``index`` field holds the index number of this control. If there
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2495) are several different controls with the same name, they can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2496) distinguished by the index number. This is the case when several
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2497) codecs exist on the card. If the index is zero, you can omit the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2498) definition above.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2499)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2500) The ``access`` field contains the access type of this control. Give
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2501) the combination of bit masks, ``SNDRV_CTL_ELEM_ACCESS_XXX``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2502) there. The details will be explained in the `Access Flags`_
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2503) subsection.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2504)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2505) The ``private_value`` field contains an arbitrary long integer value
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2506) for this record. When using the generic ``info``, ``get`` and ``put``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2507) callbacks, you can pass a value through this field. If several small
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2508) numbers are necessary, you can combine them in bitwise. Or, it's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2509) possible to give a pointer (casted to unsigned long) of some record to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2510) this field, too.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2511)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2512) The ``tlv`` field can be used to provide metadata about the control;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2513) see the `Metadata`_ subsection.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2514)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2515) The other three are `Control Callbacks`_.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2516)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2517) Control Names
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2518) -------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2519)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2520) There are some standards to define the control names. A control is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2521) usually defined from the three parts as “SOURCE DIRECTION FUNCTION”.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2522)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2523) The first, ``SOURCE``, specifies the source of the control, and is a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2524) string such as “Master”, “PCM”, “CD” and “Line”. There are many
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2525) pre-defined sources.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2526)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2527) The second, ``DIRECTION``, is one of the following strings according to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2528) the direction of the control: “Playback”, “Capture”, “Bypass Playback”
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2529) and “Bypass Capture”. Or, it can be omitted, meaning both playback and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2530) capture directions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2531)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2532) The third, ``FUNCTION``, is one of the following strings according to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2533) the function of the control: “Switch”, “Volume” and “Route”.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2534)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2535) The example of control names are, thus, “Master Capture Switch” or “PCM
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2536) Playback Volume”.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2537)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2538) There are some exceptions:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2539)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2540) Global capture and playback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2541) ~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2542)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2543) “Capture Source”, “Capture Switch” and “Capture Volume” are used for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2544) global capture (input) source, switch and volume. Similarly, “Playback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2545) Switch” and “Playback Volume” are used for the global output gain switch
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2546) and volume.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2547)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2548) Tone-controls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2549) ~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2550)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2551) tone-control switch and volumes are specified like “Tone Control - XXX”,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2552) e.g. “Tone Control - Switch”, “Tone Control - Bass”, “Tone Control -
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2553) Center”.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2554)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2555) 3D controls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2556) ~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2557)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2558) 3D-control switches and volumes are specified like “3D Control - XXX”,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2559) e.g. “3D Control - Switch”, “3D Control - Center”, “3D Control - Space”.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2560)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2561) Mic boost
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2562) ~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2563)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2564) Mic-boost switch is set as “Mic Boost” or “Mic Boost (6dB)”.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2565)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2566) More precise information can be found in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2567) ``Documentation/sound/designs/control-names.rst``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2568)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2569) Access Flags
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2570) ------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2571)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2572) The access flag is the bitmask which specifies the access type of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2573) given control. The default access type is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2574) ``SNDRV_CTL_ELEM_ACCESS_READWRITE``, which means both read and write are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2575) allowed to this control. When the access flag is omitted (i.e. = 0), it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2576) is considered as ``READWRITE`` access as default.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2577)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2578) When the control is read-only, pass ``SNDRV_CTL_ELEM_ACCESS_READ``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2579) instead. In this case, you don't have to define the ``put`` callback.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2580) Similarly, when the control is write-only (although it's a rare case),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2581) you can use the ``WRITE`` flag instead, and you don't need the ``get``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2582) callback.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2583)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2584) If the control value changes frequently (e.g. the VU meter),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2585) ``VOLATILE`` flag should be given. This means that the control may be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2586) changed without `Change notification`_. Applications should poll such
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2587) a control constantly.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2588)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2589) When the control is inactive, set the ``INACTIVE`` flag, too. There are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2590) ``LOCK`` and ``OWNER`` flags to change the write permissions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2591)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2592) Control Callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2593) -----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2594)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2595) info callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2596) ~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2597)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2598) The ``info`` callback is used to get detailed information on this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2599) control. This must store the values of the given
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2600) struct snd_ctl_elem_info object. For example,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2601) for a boolean control with a single element:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2602)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2603) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2604)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2605)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2606) static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2607) struct snd_ctl_elem_info *uinfo)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2608) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2609) uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2610) uinfo->count = 1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2611) uinfo->value.integer.min = 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2612) uinfo->value.integer.max = 1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2613) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2614) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2615)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2616)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2617)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2618) The ``type`` field specifies the type of the control. There are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2619) ``BOOLEAN``, ``INTEGER``, ``ENUMERATED``, ``BYTES``, ``IEC958`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2620) ``INTEGER64``. The ``count`` field specifies the number of elements in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2621) this control. For example, a stereo volume would have count = 2. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2622) ``value`` field is a union, and the values stored are depending on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2623) type. The boolean and integer types are identical.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2624)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2625) The enumerated type is a bit different from others. You'll need to set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2626) the string for the currently given item index.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2627)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2628) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2629)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2630) static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2631) struct snd_ctl_elem_info *uinfo)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2632) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2633) static char *texts[4] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2634) "First", "Second", "Third", "Fourth"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2635) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2636) uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2637) uinfo->count = 1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2638) uinfo->value.enumerated.items = 4;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2639) if (uinfo->value.enumerated.item > 3)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2640) uinfo->value.enumerated.item = 3;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2641) strcpy(uinfo->value.enumerated.name,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2642) texts[uinfo->value.enumerated.item]);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2643) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2644) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2645)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2646) The above callback can be simplified with a helper function,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2647) :c:func:`snd_ctl_enum_info()`. The final code looks like below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2648) (You can pass ``ARRAY_SIZE(texts)`` instead of 4 in the third argument;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2649) it's a matter of taste.)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2650)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2651) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2652)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2653) static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2654) struct snd_ctl_elem_info *uinfo)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2655) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2656) static char *texts[4] = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2657) "First", "Second", "Third", "Fourth"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2658) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2659) return snd_ctl_enum_info(uinfo, 1, 4, texts);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2660) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2661)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2662)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2663) Some common info callbacks are available for your convenience:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2664) :c:func:`snd_ctl_boolean_mono_info()` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2665) :c:func:`snd_ctl_boolean_stereo_info()`. Obviously, the former
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2666) is an info callback for a mono channel boolean item, just like
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2667) :c:func:`snd_myctl_mono_info()` above, and the latter is for a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2668) stereo channel boolean item.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2669)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2670) get callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2671) ~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2672)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2673) This callback is used to read the current value of the control and to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2674) return to user-space.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2675)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2676) For example,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2677)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2678) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2679)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2680)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2681) static int snd_myctl_get(struct snd_kcontrol *kcontrol,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2682) struct snd_ctl_elem_value *ucontrol)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2683) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2684) struct mychip *chip = snd_kcontrol_chip(kcontrol);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2685) ucontrol->value.integer.value[0] = get_some_value(chip);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2686) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2687) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2688)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2689)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2690)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2691) The ``value`` field depends on the type of control as well as on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2692) info callback. For example, the sb driver uses this field to store the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2693) register offset, the bit-shift and the bit-mask. The ``private_value``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2694) field is set as follows:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2695)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2696) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2697)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2698) .private_value = reg | (shift << 16) | (mask << 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2699)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2700) and is retrieved in callbacks like
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2701)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2702) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2703)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2704) static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2705) struct snd_ctl_elem_value *ucontrol)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2706) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2707) int reg = kcontrol->private_value & 0xff;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2708) int shift = (kcontrol->private_value >> 16) & 0xff;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2709) int mask = (kcontrol->private_value >> 24) & 0xff;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2710) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2711) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2712)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2713) In the ``get`` callback, you have to fill all the elements if the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2714) control has more than one elements, i.e. ``count > 1``. In the example
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2715) above, we filled only one element (``value.integer.value[0]``) since
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2716) it's assumed as ``count = 1``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2717)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2718) put callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2719) ~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2720)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2721) This callback is used to write a value from user-space.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2722)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2723) For example,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2724)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2725) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2726)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2727)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2728) static int snd_myctl_put(struct snd_kcontrol *kcontrol,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2729) struct snd_ctl_elem_value *ucontrol)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2730) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2731) struct mychip *chip = snd_kcontrol_chip(kcontrol);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2732) int changed = 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2733) if (chip->current_value !=
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2734) ucontrol->value.integer.value[0]) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2735) change_current_value(chip,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2736) ucontrol->value.integer.value[0]);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2737) changed = 1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2738) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2739) return changed;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2740) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2741)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2742)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2743)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2744) As seen above, you have to return 1 if the value is changed. If the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2745) value is not changed, return 0 instead. If any fatal error happens,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2746) return a negative error code as usual.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2747)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2748) As in the ``get`` callback, when the control has more than one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2749) elements, all elements must be evaluated in this callback, too.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2750)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2751) Callbacks are not atomic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2752) ~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2753)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2754) All these three callbacks are basically not atomic.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2755)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2756) Control Constructor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2757) -------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2758)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2759) When everything is ready, finally we can create a new control. To create
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2760) a control, there are two functions to be called,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2761) :c:func:`snd_ctl_new1()` and :c:func:`snd_ctl_add()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2762)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2763) In the simplest way, you can do like this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2764)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2765) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2766)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2767) err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2768) if (err < 0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2769) return err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2770)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2771) where ``my_control`` is the struct snd_kcontrol_new object defined above,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2772) and chip is the object pointer to be passed to kcontrol->private_data which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2773) can be referred to in callbacks.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2774)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2775) :c:func:`snd_ctl_new1()` allocates a new struct snd_kcontrol instance, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2776) :c:func:`snd_ctl_add()` assigns the given control component to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2777) card.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2778)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2779) Change Notification
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2780) -------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2781)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2782) If you need to change and update a control in the interrupt routine, you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2783) can call :c:func:`snd_ctl_notify()`. For example,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2784)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2785) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2786)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2787) snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2788)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2789) This function takes the card pointer, the event-mask, and the control id
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2790) pointer for the notification. The event-mask specifies the types of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2791) notification, for example, in the above example, the change of control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2792) values is notified. The id pointer is the pointer of struct snd_ctl_elem_id
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2793) to be notified. You can find some examples in ``es1938.c`` or ``es1968.c``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2794) for hardware volume interrupts.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2795)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2796) Metadata
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2797) --------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2798)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2799) To provide information about the dB values of a mixer control, use on of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2800) the ``DECLARE_TLV_xxx`` macros from ``<sound/tlv.h>`` to define a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2801) variable containing this information, set the ``tlv.p`` field to point to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2802) this variable, and include the ``SNDRV_CTL_ELEM_ACCESS_TLV_READ`` flag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2803) in the ``access`` field; like this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2804)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2805) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2806)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2807) static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2808)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2809) static struct snd_kcontrol_new my_control = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2810) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2811) .access = SNDRV_CTL_ELEM_ACCESS_READWRITE |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2812) SNDRV_CTL_ELEM_ACCESS_TLV_READ,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2813) ...
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2814) .tlv.p = db_scale_my_control,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2815) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2816)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2817)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2818) The :c:func:`DECLARE_TLV_DB_SCALE()` macro defines information
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2819) about a mixer control where each step in the control's value changes the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2820) dB value by a constant dB amount. The first parameter is the name of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2821) variable to be defined. The second parameter is the minimum value, in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2822) units of 0.01 dB. The third parameter is the step size, in units of 0.01
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2823) dB. Set the fourth parameter to 1 if the minimum value actually mutes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2824) the control.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2825)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2826) The :c:func:`DECLARE_TLV_DB_LINEAR()` macro defines information
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2827) about a mixer control where the control's value affects the output
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2828) linearly. The first parameter is the name of the variable to be defined.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2829) The second parameter is the minimum value, in units of 0.01 dB. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2830) third parameter is the maximum value, in units of 0.01 dB. If the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2831) minimum value mutes the control, set the second parameter to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2832) ``TLV_DB_GAIN_MUTE``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2833)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2834) API for AC97 Codec
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2835) ==================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2836)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2837) General
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2838) -------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2839)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2840) The ALSA AC97 codec layer is a well-defined one, and you don't have to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2841) write much code to control it. Only low-level control routines are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2842) necessary. The AC97 codec API is defined in ``<sound/ac97_codec.h>``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2843)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2844) Full Code Example
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2845) -----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2846)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2847) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2848)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2849) struct mychip {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2850) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2851) struct snd_ac97 *ac97;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2852) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2853) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2854)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2855) static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2856) unsigned short reg)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2857) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2858) struct mychip *chip = ac97->private_data;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2859) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2860) /* read a register value here from the codec */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2861) return the_register_value;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2862) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2863)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2864) static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2865) unsigned short reg, unsigned short val)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2866) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2867) struct mychip *chip = ac97->private_data;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2868) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2869) /* write the given register value to the codec */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2870) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2871)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2872) static int snd_mychip_ac97(struct mychip *chip)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2873) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2874) struct snd_ac97_bus *bus;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2875) struct snd_ac97_template ac97;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2876) int err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2877) static struct snd_ac97_bus_ops ops = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2878) .write = snd_mychip_ac97_write,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2879) .read = snd_mychip_ac97_read,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2880) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2881)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2882) err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2883) if (err < 0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2884) return err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2885) memset(&ac97, 0, sizeof(ac97));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2886) ac97.private_data = chip;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2887) return snd_ac97_mixer(bus, &ac97, &chip->ac97);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2888) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2889)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2890)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2891) AC97 Constructor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2892) ----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2893)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2894) To create an ac97 instance, first call :c:func:`snd_ac97_bus()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2895) with an ``ac97_bus_ops_t`` record with callback functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2896)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2897) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2898)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2899) struct snd_ac97_bus *bus;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2900) static struct snd_ac97_bus_ops ops = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2901) .write = snd_mychip_ac97_write,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2902) .read = snd_mychip_ac97_read,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2903) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2904)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2905) snd_ac97_bus(card, 0, &ops, NULL, &pbus);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2906)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2907) The bus record is shared among all belonging ac97 instances.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2908)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2909) And then call :c:func:`snd_ac97_mixer()` with an struct snd_ac97_template
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2910) record together with the bus pointer created above.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2911)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2912) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2913)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2914) struct snd_ac97_template ac97;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2915) int err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2916)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2917) memset(&ac97, 0, sizeof(ac97));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2918) ac97.private_data = chip;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2919) snd_ac97_mixer(bus, &ac97, &chip->ac97);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2920)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2921) where chip->ac97 is a pointer to a newly created ``ac97_t``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2922) instance. In this case, the chip pointer is set as the private data,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2923) so that the read/write callback functions can refer to this chip
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2924) instance. This instance is not necessarily stored in the chip
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2925) record. If you need to change the register values from the driver, or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2926) need the suspend/resume of ac97 codecs, keep this pointer to pass to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2927) the corresponding functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2928)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2929) AC97 Callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2930) --------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2931)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2932) The standard callbacks are ``read`` and ``write``. Obviously they
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2933) correspond to the functions for read and write accesses to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2934) hardware low-level codes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2935)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2936) The ``read`` callback returns the register value specified in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2937) argument.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2938)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2939) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2940)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2941) static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2942) unsigned short reg)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2943) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2944) struct mychip *chip = ac97->private_data;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2945) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2946) return the_register_value;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2947) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2948)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2949) Here, the chip can be cast from ``ac97->private_data``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2950)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2951) Meanwhile, the ``write`` callback is used to set the register
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2952) value
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2953)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2954) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2955)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2956) static void snd_mychip_ac97_write(struct snd_ac97 *ac97,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2957) unsigned short reg, unsigned short val)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2958)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2959)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2960) These callbacks are non-atomic like the control API callbacks.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2961)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2962) There are also other callbacks: ``reset``, ``wait`` and ``init``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2963)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2964) The ``reset`` callback is used to reset the codec. If the chip
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2965) requires a special kind of reset, you can define this callback.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2966)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2967) The ``wait`` callback is used to add some waiting time in the standard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2968) initialization of the codec. If the chip requires the extra waiting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2969) time, define this callback.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2970)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2971) The ``init`` callback is used for additional initialization of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2972) codec.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2973)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2974) Updating Registers in The Driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2975) --------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2976)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2977) If you need to access to the codec from the driver, you can call the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2978) following functions: :c:func:`snd_ac97_write()`,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2979) :c:func:`snd_ac97_read()`, :c:func:`snd_ac97_update()` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2980) :c:func:`snd_ac97_update_bits()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2981)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2982) Both :c:func:`snd_ac97_write()` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2983) :c:func:`snd_ac97_update()` functions are used to set a value to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2984) the given register (``AC97_XXX``). The difference between them is that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2985) :c:func:`snd_ac97_update()` doesn't write a value if the given
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2986) value has been already set, while :c:func:`snd_ac97_write()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2987) always rewrites the value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2988)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2989) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2990)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2991) snd_ac97_write(ac97, AC97_MASTER, 0x8080);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2992) snd_ac97_update(ac97, AC97_MASTER, 0x8080);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2993)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2994) :c:func:`snd_ac97_read()` is used to read the value of the given
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2995) register. For example,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2996)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2997) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2998)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2999) value = snd_ac97_read(ac97, AC97_MASTER);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3000)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3001) :c:func:`snd_ac97_update_bits()` is used to update some bits in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3002) the given register.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3003)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3004) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3005)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3006) snd_ac97_update_bits(ac97, reg, mask, value);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3007)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3008) Also, there is a function to change the sample rate (of a given register
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3009) such as ``AC97_PCM_FRONT_DAC_RATE``) when VRA or DRA is supported by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3010) codec: :c:func:`snd_ac97_set_rate()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3011)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3012) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3013)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3014) snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3015)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3016)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3017) The following registers are available to set the rate:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3018) ``AC97_PCM_MIC_ADC_RATE``, ``AC97_PCM_FRONT_DAC_RATE``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3019) ``AC97_PCM_LR_ADC_RATE``, ``AC97_SPDIF``. When ``AC97_SPDIF`` is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3020) specified, the register is not really changed but the corresponding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3021) IEC958 status bits will be updated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3022)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3023) Clock Adjustment
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3024) ----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3025)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3026) In some chips, the clock of the codec isn't 48000 but using a PCI clock
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3027) (to save a quartz!). In this case, change the field ``bus->clock`` to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3028) the corresponding value. For example, intel8x0 and es1968 drivers have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3029) their own function to read from the clock.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3030)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3031) Proc Files
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3032) ----------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3033)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3034) The ALSA AC97 interface will create a proc file such as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3035) ``/proc/asound/card0/codec97#0/ac97#0-0`` and ``ac97#0-0+regs``. You
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3036) can refer to these files to see the current status and registers of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3037) the codec.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3038)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3039) Multiple Codecs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3040) ---------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3041)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3042) When there are several codecs on the same card, you need to call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3043) :c:func:`snd_ac97_mixer()` multiple times with ``ac97.num=1`` or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3044) greater. The ``num`` field specifies the codec number.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3045)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3046) If you set up multiple codecs, you either need to write different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3047) callbacks for each codec or check ``ac97->num`` in the callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3048) routines.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3049)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3050) MIDI (MPU401-UART) Interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3051) ============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3052)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3053) General
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3054) -------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3055)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3056) Many soundcards have built-in MIDI (MPU401-UART) interfaces. When the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3057) soundcard supports the standard MPU401-UART interface, most likely you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3058) can use the ALSA MPU401-UART API. The MPU401-UART API is defined in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3059) ``<sound/mpu401.h>``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3060)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3061) Some soundchips have a similar but slightly different implementation of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3062) mpu401 stuff. For example, emu10k1 has its own mpu401 routines.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3063)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3064) MIDI Constructor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3065) ----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3066)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3067) To create a rawmidi object, call :c:func:`snd_mpu401_uart_new()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3068)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3069) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3070)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3071) struct snd_rawmidi *rmidi;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3072) snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3073) irq, &rmidi);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3074)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3075)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3076) The first argument is the card pointer, and the second is the index of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3077) this component. You can create up to 8 rawmidi devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3078)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3079) The third argument is the type of the hardware, ``MPU401_HW_XXX``. If
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3080) it's not a special one, you can use ``MPU401_HW_MPU401``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3081)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3082) The 4th argument is the I/O port address. Many backward-compatible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3083) MPU401 have an I/O port such as 0x330. Or, it might be a part of its own
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3084) PCI I/O region. It depends on the chip design.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3085)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3086) The 5th argument is a bitflag for additional information. When the I/O
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3087) port address above is part of the PCI I/O region, the MPU401 I/O port
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3088) might have been already allocated (reserved) by the driver itself. In
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3089) such a case, pass a bit flag ``MPU401_INFO_INTEGRATED``, and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3090) mpu401-uart layer will allocate the I/O ports by itself.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3091)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3092) When the controller supports only the input or output MIDI stream, pass
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3093) the ``MPU401_INFO_INPUT`` or ``MPU401_INFO_OUTPUT`` bitflag,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3094) respectively. Then the rawmidi instance is created as a single stream.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3095)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3096) ``MPU401_INFO_MMIO`` bitflag is used to change the access method to MMIO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3097) (via readb and writeb) instead of iob and outb. In this case, you have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3098) to pass the iomapped address to :c:func:`snd_mpu401_uart_new()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3099)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3100) When ``MPU401_INFO_TX_IRQ`` is set, the output stream isn't checked in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3101) the default interrupt handler. The driver needs to call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3102) :c:func:`snd_mpu401_uart_interrupt_tx()` by itself to start
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3103) processing the output stream in the irq handler.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3105) If the MPU-401 interface shares its interrupt with the other logical
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3106) devices on the card, set ``MPU401_INFO_IRQ_HOOK`` (see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3107) `below <#MIDI-Interrupt-Handler>`__).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3109) Usually, the port address corresponds to the command port and port + 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3110) corresponds to the data port. If not, you may change the ``cport``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3111) field of struct snd_mpu401 manually afterward.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3112) However, struct snd_mpu401 pointer is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3113) not returned explicitly by :c:func:`snd_mpu401_uart_new()`. You
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3114) need to cast ``rmidi->private_data`` to struct snd_mpu401 explicitly,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3115)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3116) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3118) struct snd_mpu401 *mpu;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3119) mpu = rmidi->private_data;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3120)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3121) and reset the ``cport`` as you like:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3122)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3123) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3124)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3125) mpu->cport = my_own_control_port;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3126)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3127) The 6th argument specifies the ISA irq number that will be allocated. If
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3128) no interrupt is to be allocated (because your code is already allocating
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3129) a shared interrupt, or because the device does not use interrupts), pass
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3130) -1 instead. For a MPU-401 device without an interrupt, a polling timer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3131) will be used instead.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3132)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3133) MIDI Interrupt Handler
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3134) ----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3135)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3136) When the interrupt is allocated in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3137) :c:func:`snd_mpu401_uart_new()`, an exclusive ISA interrupt
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3138) handler is automatically used, hence you don't have anything else to do
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3139) than creating the mpu401 stuff. Otherwise, you have to set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3140) ``MPU401_INFO_IRQ_HOOK``, and call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3141) :c:func:`snd_mpu401_uart_interrupt()` explicitly from your own
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3142) interrupt handler when it has determined that a UART interrupt has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3143) occurred.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3144)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3145) In this case, you need to pass the private_data of the returned rawmidi
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3146) object from :c:func:`snd_mpu401_uart_new()` as the second
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3147) argument of :c:func:`snd_mpu401_uart_interrupt()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3148)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3149) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3150)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3151) snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3152)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3153)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3154) RawMIDI Interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3155) =================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3156)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3157) Overview
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3158) --------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3159)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3160) The raw MIDI interface is used for hardware MIDI ports that can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3161) accessed as a byte stream. It is not used for synthesizer chips that do
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3162) not directly understand MIDI.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3163)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3164) ALSA handles file and buffer management. All you have to do is to write
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3165) some code to move data between the buffer and the hardware.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3166)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3167) The rawmidi API is defined in ``<sound/rawmidi.h>``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3168)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3169) RawMIDI Constructor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3170) -------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3171)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3172) To create a rawmidi device, call the :c:func:`snd_rawmidi_new()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3173) function:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3174)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3175) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3176)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3177) struct snd_rawmidi *rmidi;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3178) err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3179) if (err < 0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3180) return err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3181) rmidi->private_data = chip;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3182) strcpy(rmidi->name, "My MIDI");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3183) rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3184) SNDRV_RAWMIDI_INFO_INPUT |
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3185) SNDRV_RAWMIDI_INFO_DUPLEX;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3186)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3187) The first argument is the card pointer, the second argument is the ID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3188) string.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3189)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3190) The third argument is the index of this component. You can create up to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3191) 8 rawmidi devices.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3192)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3193) The fourth and fifth arguments are the number of output and input
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3194) substreams, respectively, of this device (a substream is the equivalent
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3195) of a MIDI port).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3196)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3197) Set the ``info_flags`` field to specify the capabilities of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3198) device. Set ``SNDRV_RAWMIDI_INFO_OUTPUT`` if there is at least one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3199) output port, ``SNDRV_RAWMIDI_INFO_INPUT`` if there is at least one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3200) input port, and ``SNDRV_RAWMIDI_INFO_DUPLEX`` if the device can handle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3201) output and input at the same time.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3202)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3203) After the rawmidi device is created, you need to set the operators
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3204) (callbacks) for each substream. There are helper functions to set the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3205) operators for all the substreams of a device:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3206)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3207) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3208)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3209) snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3210) snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3211)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3212) The operators are usually defined like this:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3213)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3214) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3215)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3216) static struct snd_rawmidi_ops snd_mymidi_output_ops = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3217) .open = snd_mymidi_output_open,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3218) .close = snd_mymidi_output_close,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3219) .trigger = snd_mymidi_output_trigger,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3220) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3221)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3222) These callbacks are explained in the `RawMIDI Callbacks`_ section.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3223)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3224) If there are more than one substream, you should give a unique name to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3225) each of them:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3226)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3227) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3228)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3229) struct snd_rawmidi_substream *substream;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3230) list_for_each_entry(substream,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3231) &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3232) list {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3233) sprintf(substream->name, "My MIDI Port %d", substream->number + 1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3234) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3235) /* same for SNDRV_RAWMIDI_STREAM_INPUT */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3236)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3237) RawMIDI Callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3238) -----------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3239)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3240) In all the callbacks, the private data that you've set for the rawmidi
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3241) device can be accessed as ``substream->rmidi->private_data``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3242)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3243) If there is more than one port, your callbacks can determine the port
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3244) index from the struct snd_rawmidi_substream data passed to each
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3245) callback:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3246)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3247) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3248)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3249) struct snd_rawmidi_substream *substream;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3250) int index = substream->number;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3251)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3252) RawMIDI open callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3253) ~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3254)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3255) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3256)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3257) static int snd_xxx_open(struct snd_rawmidi_substream *substream);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3258)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3259)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3260) This is called when a substream is opened. You can initialize the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3261) hardware here, but you shouldn't start transmitting/receiving data yet.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3262)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3263) RawMIDI close callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3264) ~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3265)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3266) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3267)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3268) static int snd_xxx_close(struct snd_rawmidi_substream *substream);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3269)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3270) Guess what.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3271)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3272) The ``open`` and ``close`` callbacks of a rawmidi device are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3273) serialized with a mutex, and can sleep.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3274)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3275) Rawmidi trigger callback for output substreams
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3276) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3277)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3278) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3279)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3280) static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3281)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3282)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3283) This is called with a nonzero ``up`` parameter when there is some data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3284) in the substream buffer that must be transmitted.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3285)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3286) To read data from the buffer, call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3287) :c:func:`snd_rawmidi_transmit_peek()`. It will return the number
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3288) of bytes that have been read; this will be less than the number of bytes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3289) requested when there are no more data in the buffer. After the data have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3290) been transmitted successfully, call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3291) :c:func:`snd_rawmidi_transmit_ack()` to remove the data from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3292) substream buffer:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3293)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3294) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3295)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3296) unsigned char data;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3297) while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3298) if (snd_mychip_try_to_transmit(data))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3299) snd_rawmidi_transmit_ack(substream, 1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3300) else
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3301) break; /* hardware FIFO full */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3302) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3303)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3304) If you know beforehand that the hardware will accept data, you can use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3305) the :c:func:`snd_rawmidi_transmit()` function which reads some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3306) data and removes them from the buffer at once:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3307)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3308) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3309)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3310) while (snd_mychip_transmit_possible()) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3311) unsigned char data;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3312) if (snd_rawmidi_transmit(substream, &data, 1) != 1)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3313) break; /* no more data */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3314) snd_mychip_transmit(data);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3315) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3316)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3317) If you know beforehand how many bytes you can accept, you can use a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3318) buffer size greater than one with the ``snd_rawmidi_transmit*()`` functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3319)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3320) The ``trigger`` callback must not sleep. If the hardware FIFO is full
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3321) before the substream buffer has been emptied, you have to continue
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3322) transmitting data later, either in an interrupt handler, or with a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3323) timer if the hardware doesn't have a MIDI transmit interrupt.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3324)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3325) The ``trigger`` callback is called with a zero ``up`` parameter when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3326) the transmission of data should be aborted.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3327)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3328) RawMIDI trigger callback for input substreams
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3329) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3330)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3331) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3332)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3333) static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3334)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3335)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3336) This is called with a nonzero ``up`` parameter to enable receiving data,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3337) or with a zero ``up`` parameter do disable receiving data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3338)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3339) The ``trigger`` callback must not sleep; the actual reading of data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3340) from the device is usually done in an interrupt handler.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3341)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3342) When data reception is enabled, your interrupt handler should call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3343) :c:func:`snd_rawmidi_receive()` for all received data:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3344)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3345) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3346)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3347) void snd_mychip_midi_interrupt(...)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3348) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3349) while (mychip_midi_available()) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3350) unsigned char data;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3351) data = mychip_midi_read();
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3352) snd_rawmidi_receive(substream, &data, 1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3353) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3354) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3355)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3356)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3357) drain callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3358) ~~~~~~~~~~~~~~
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3359)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3360) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3361)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3362) static void snd_xxx_drain(struct snd_rawmidi_substream *substream);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3363)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3364)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3365) This is only used with output substreams. This function should wait
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3366) until all data read from the substream buffer have been transmitted.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3367) This ensures that the device can be closed and the driver unloaded
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3368) without losing data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3369)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3370) This callback is optional. If you do not set ``drain`` in the struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3371) snd_rawmidi_ops structure, ALSA will simply wait for 50 milliseconds
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3372) instead.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3373)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3374) Miscellaneous Devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3375) =====================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3376)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3377) FM OPL3
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3378) -------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3379)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3380) The FM OPL3 is still used in many chips (mainly for backward
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3381) compatibility). ALSA has a nice OPL3 FM control layer, too. The OPL3 API
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3382) is defined in ``<sound/opl3.h>``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3383)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3384) FM registers can be directly accessed through the direct-FM API, defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3385) in ``<sound/asound_fm.h>``. In ALSA native mode, FM registers are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3386) accessed through the Hardware-Dependent Device direct-FM extension API,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3387) whereas in OSS compatible mode, FM registers can be accessed with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3388) OSS direct-FM compatible API in ``/dev/dmfmX`` device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3389)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3390) To create the OPL3 component, you have two functions to call. The first
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3391) one is a constructor for the ``opl3_t`` instance.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3392)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3393) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3394)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3395) struct snd_opl3 *opl3;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3396) snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3397) integrated, &opl3);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3398)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3399) The first argument is the card pointer, the second one is the left port
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3400) address, and the third is the right port address. In most cases, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3401) right port is placed at the left port + 2.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3402)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3403) The fourth argument is the hardware type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3404)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3405) When the left and right ports have been already allocated by the card
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3406) driver, pass non-zero to the fifth argument (``integrated``). Otherwise,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3407) the opl3 module will allocate the specified ports by itself.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3408)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3409) When the accessing the hardware requires special method instead of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3410) standard I/O access, you can create opl3 instance separately with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3411) :c:func:`snd_opl3_new()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3412)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3413) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3414)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3415) struct snd_opl3 *opl3;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3416) snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3417)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3418) Then set ``command``, ``private_data`` and ``private_free`` for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3419) private access function, the private data and the destructor. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3420) ``l_port`` and ``r_port`` are not necessarily set. Only the command
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3421) must be set properly. You can retrieve the data from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3422) ``opl3->private_data`` field.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3423)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3424) After creating the opl3 instance via :c:func:`snd_opl3_new()`,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3425) call :c:func:`snd_opl3_init()` to initialize the chip to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3426) proper state. Note that :c:func:`snd_opl3_create()` always calls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3427) it internally.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3428)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3429) If the opl3 instance is created successfully, then create a hwdep device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3430) for this opl3.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3431)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3432) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3433)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3434) struct snd_hwdep *opl3hwdep;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3435) snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3436)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3437) The first argument is the ``opl3_t`` instance you created, and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3438) second is the index number, usually 0.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3439)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3440) The third argument is the index-offset for the sequencer client assigned
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3441) to the OPL3 port. When there is an MPU401-UART, give 1 for here (UART
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3442) always takes 0).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3443)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3444) Hardware-Dependent Devices
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3445) --------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3446)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3447) Some chips need user-space access for special controls or for loading
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3448) the micro code. In such a case, you can create a hwdep
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3449) (hardware-dependent) device. The hwdep API is defined in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3450) ``<sound/hwdep.h>``. You can find examples in opl3 driver or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3451) ``isa/sb/sb16_csp.c``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3452)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3453) The creation of the ``hwdep`` instance is done via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3454) :c:func:`snd_hwdep_new()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3455)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3456) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3457)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3458) struct snd_hwdep *hw;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3459) snd_hwdep_new(card, "My HWDEP", 0, &hw);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3460)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3461) where the third argument is the index number.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3462)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3463) You can then pass any pointer value to the ``private_data``. If you
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3464) assign a private data, you should define the destructor, too. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3465) destructor function is set in the ``private_free`` field.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3466)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3467) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3468)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3469) struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3470) hw->private_data = p;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3471) hw->private_free = mydata_free;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3472)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3473) and the implementation of the destructor would be:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3474)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3475) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3476)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3477) static void mydata_free(struct snd_hwdep *hw)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3478) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3479) struct mydata *p = hw->private_data;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3480) kfree(p);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3481) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3482)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3483) The arbitrary file operations can be defined for this instance. The file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3484) operators are defined in the ``ops`` table. For example, assume that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3485) this chip needs an ioctl.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3486)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3487) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3488)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3489) hw->ops.open = mydata_open;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3490) hw->ops.ioctl = mydata_ioctl;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3491) hw->ops.release = mydata_release;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3492)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3493) And implement the callback functions as you like.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3494)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3495) IEC958 (S/PDIF)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3496) ---------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3497)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3498) Usually the controls for IEC958 devices are implemented via the control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3499) interface. There is a macro to compose a name string for IEC958
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3500) controls, :c:func:`SNDRV_CTL_NAME_IEC958()` defined in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3501) ``<include/asound.h>``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3502)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3503) There are some standard controls for IEC958 status bits. These controls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3504) use the type ``SNDRV_CTL_ELEM_TYPE_IEC958``, and the size of element is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3505) fixed as 4 bytes array (value.iec958.status[x]). For the ``info``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3506) callback, you don't specify the value field for this type (the count
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3507) field must be set, though).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3508)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3509) “IEC958 Playback Con Mask” is used to return the bit-mask for the IEC958
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3510) status bits of consumer mode. Similarly, “IEC958 Playback Pro Mask”
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3511) returns the bitmask for professional mode. They are read-only controls.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3512)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3513) Meanwhile, “IEC958 Playback Default” control is defined for getting and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3514) setting the current default IEC958 bits.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3515)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3516) Due to historical reasons, both variants of the Playback Mask and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3517) Playback Default controls can be implemented on either a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3518) ``SNDRV_CTL_ELEM_IFACE_PCM`` or a ``SNDRV_CTL_ELEM_IFACE_MIXER`` iface.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3519) Drivers should expose the mask and default on the same iface though.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3520)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3521) In addition, you can define the control switches to enable/disable or to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3522) set the raw bit mode. The implementation will depend on the chip, but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3523) the control should be named as “IEC958 xxx”, preferably using the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3524) :c:func:`SNDRV_CTL_NAME_IEC958()` macro.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3525)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3526) You can find several cases, for example, ``pci/emu10k1``,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3527) ``pci/ice1712``, or ``pci/cmipci.c``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3528)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3529) Buffer and Memory Management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3530) ============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3531)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3532) Buffer Types
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3533) ------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3534)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3535) ALSA provides several different buffer allocation functions depending on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3536) the bus and the architecture. All these have a consistent API. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3537) allocation of physically-contiguous pages is done via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3538) :c:func:`snd_malloc_xxx_pages()` function, where xxx is the bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3539) type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3540)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3541) The allocation of pages with fallback is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3542) :c:func:`snd_malloc_xxx_pages_fallback()`. This function tries
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3543) to allocate the specified pages but if the pages are not available, it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3544) tries to reduce the page sizes until enough space is found.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3545)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3546) The release the pages, call :c:func:`snd_free_xxx_pages()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3547) function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3548)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3549) Usually, ALSA drivers try to allocate and reserve a large contiguous
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3550) physical space at the time the module is loaded for the later use. This
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3551) is called “pre-allocation”. As already written, you can call the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3552) following function at pcm instance construction time (in the case of PCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3553) bus).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3554)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3555) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3556)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3557) snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3558) &pci->dev, size, max);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3559)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3560) where ``size`` is the byte size to be pre-allocated and the ``max`` is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3561) the maximum size to be changed via the ``prealloc`` proc file. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3562) allocator will try to get an area as large as possible within the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3563) given size.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3564)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3565) The second argument (type) and the third argument (device pointer) are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3566) dependent on the bus. For normal devices, pass the device pointer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3567) (typically identical as ``card->dev``) to the third argument with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3568) ``SNDRV_DMA_TYPE_DEV`` type. For the continuous buffer unrelated to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3569) bus can be pre-allocated with ``SNDRV_DMA_TYPE_CONTINUOUS`` type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3570) You can pass NULL to the device pointer in that case, which is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3571) default mode implying to allocate with ``GFP_KERNEL`` flag.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3572) If you need a different GFP flag, you can pass it by encoding the flag
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3573) into the device pointer via a special macro
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3574) :c:func:`snd_dma_continuous_data()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3575) For the scatter-gather buffers, use ``SNDRV_DMA_TYPE_DEV_SG`` with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3576) device pointer (see the `Non-Contiguous Buffers`_ section).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3577)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3578) Once the buffer is pre-allocated, you can use the allocator in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3579) ``hw_params`` callback:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3580)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3581) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3582)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3583) snd_pcm_lib_malloc_pages(substream, size);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3584)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3585) Note that you have to pre-allocate to use this function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3586)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3587) Most of drivers use, though, rather the newly introduced "managed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3588) buffer allocation mode" instead of the manual allocation or release.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3589) This is done by calling :c:func:`snd_pcm_set_managed_buffer_all()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3590) instead of :c:func:`snd_pcm_lib_preallocate_pages_for_all()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3591)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3592) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3593)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3594) snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3595) &pci->dev, size, max);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3596)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3597) where passed arguments are identical in both functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3598) The difference in the managed mode is that PCM core will call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3599) :c:func:`snd_pcm_lib_malloc_pages()` internally already before calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3600) the PCM ``hw_params`` callback, and call :c:func:`snd_pcm_lib_free_pages()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3601) after the PCM ``hw_free`` callback automatically. So the driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3602) doesn't have to call these functions explicitly in its callback any
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3603) longer. This made many driver code having NULL ``hw_params`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3604) ``hw_free`` entries.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3605)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3606) External Hardware Buffers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3607) -------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3608)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3609) Some chips have their own hardware buffers and the DMA transfer from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3610) host memory is not available. In such a case, you need to either 1)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3611) copy/set the audio data directly to the external hardware buffer, or 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3612) make an intermediate buffer and copy/set the data from it to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3613) external hardware buffer in interrupts (or in tasklets, preferably).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3614)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3615) The first case works fine if the external hardware buffer is large
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3616) enough. This method doesn't need any extra buffers and thus is more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3617) effective. You need to define the ``copy_user`` and ``copy_kernel``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3618) callbacks for the data transfer, in addition to ``fill_silence``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3619) callback for playback. However, there is a drawback: it cannot be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3620) mmapped. The examples are GUS's GF1 PCM or emu8000's wavetable PCM.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3621)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3622) The second case allows for mmap on the buffer, although you have to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3623) handle an interrupt or a tasklet to transfer the data from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3624) intermediate buffer to the hardware buffer. You can find an example in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3625) the vxpocket driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3626)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3627) Another case is when the chip uses a PCI memory-map region for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3628) buffer instead of the host memory. In this case, mmap is available only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3629) on certain architectures like the Intel one. In non-mmap mode, the data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3630) cannot be transferred as in the normal way. Thus you need to define the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3631) ``copy_user``, ``copy_kernel`` and ``fill_silence`` callbacks as well,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3632) as in the cases above. The examples are found in ``rme32.c`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3633) ``rme96.c``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3634)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3635) The implementation of the ``copy_user``, ``copy_kernel`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3636) ``silence`` callbacks depends upon whether the hardware supports
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3637) interleaved or non-interleaved samples. The ``copy_user`` callback is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3638) defined like below, a bit differently depending whether the direction
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3639) is playback or capture:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3640)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3641) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3642)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3643) static int playback_copy_user(struct snd_pcm_substream *substream,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3644) int channel, unsigned long pos,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3645) void __user *src, unsigned long count);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3646) static int capture_copy_user(struct snd_pcm_substream *substream,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3647) int channel, unsigned long pos,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3648) void __user *dst, unsigned long count);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3649)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3650) In the case of interleaved samples, the second argument (``channel``) is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3651) not used. The third argument (``pos``) points the current position
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3652) offset in bytes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3653)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3654) The meaning of the fourth argument is different between playback and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3655) capture. For playback, it holds the source data pointer, and for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3656) capture, it's the destination data pointer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3657)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3658) The last argument is the number of bytes to be copied.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3659)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3660) What you have to do in this callback is again different between playback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3661) and capture directions. In the playback case, you copy the given amount
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3662) of data (``count``) at the specified pointer (``src``) to the specified
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3663) offset (``pos``) on the hardware buffer. When coded like memcpy-like
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3664) way, the copy would be like:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3665)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3666) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3667)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3668) my_memcpy_from_user(my_buffer + pos, src, count);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3669)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3670) For the capture direction, you copy the given amount of data (``count``)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3671) at the specified offset (``pos``) on the hardware buffer to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3672) specified pointer (``dst``).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3673)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3674) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3675)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3676) my_memcpy_to_user(dst, my_buffer + pos, count);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3677)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3678) Here the functions are named as ``from_user`` and ``to_user`` because
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3679) it's the user-space buffer that is passed to these callbacks. That
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3680) is, the callback is supposed to copy from/to the user-space data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3681) directly to/from the hardware buffer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3682)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3683) Careful readers might notice that these callbacks receive the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3684) arguments in bytes, not in frames like other callbacks. It's because
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3685) it would make coding easier like the examples above, and also it makes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3686) easier to unify both the interleaved and non-interleaved cases, as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3687) explained in the following.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3688)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3689) In the case of non-interleaved samples, the implementation will be a bit
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3690) more complicated. The callback is called for each channel, passed by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3691) the second argument, so totally it's called for N-channels times per
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3692) transfer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3693)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3694) The meaning of other arguments are almost same as the interleaved
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3695) case. The callback is supposed to copy the data from/to the given
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3696) user-space buffer, but only for the given channel. For the detailed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3697) implementations, please check ``isa/gus/gus_pcm.c`` or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3698) "pci/rme9652/rme9652.c" as examples.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3699)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3700) The above callbacks are the copy from/to the user-space buffer. There
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3701) are some cases where we want copy from/to the kernel-space buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3702) instead. In such a case, ``copy_kernel`` callback is called. It'd
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3703) look like:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3704)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3705) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3706)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3707) static int playback_copy_kernel(struct snd_pcm_substream *substream,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3708) int channel, unsigned long pos,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3709) void *src, unsigned long count);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3710) static int capture_copy_kernel(struct snd_pcm_substream *substream,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3711) int channel, unsigned long pos,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3712) void *dst, unsigned long count);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3713)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3714) As found easily, the only difference is that the buffer pointer is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3715) without ``__user`` prefix; that is, a kernel-buffer pointer is passed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3716) in the fourth argument. Correspondingly, the implementation would be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3717) a version without the user-copy, such as:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3718)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3719) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3720)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3721) my_memcpy(my_buffer + pos, src, count);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3722)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3723) Usually for the playback, another callback ``fill_silence`` is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3724) defined. It's implemented in a similar way as the copy callbacks
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3725) above:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3726)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3727) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3728)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3729) static int silence(struct snd_pcm_substream *substream, int channel,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3730) unsigned long pos, unsigned long count);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3731)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3732) The meanings of arguments are the same as in the ``copy_user`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3733) ``copy_kernel`` callbacks, although there is no buffer pointer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3734) argument. In the case of interleaved samples, the channel argument has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3735) no meaning, as well as on ``copy_*`` callbacks.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3736)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3737) The role of ``fill_silence`` callback is to set the given amount
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3738) (``count``) of silence data at the specified offset (``pos``) on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3739) hardware buffer. Suppose that the data format is signed (that is, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3740) silent-data is 0), and the implementation using a memset-like function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3741) would be like:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3742)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3743) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3744)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3745) my_memset(my_buffer + pos, 0, count);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3746)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3747) In the case of non-interleaved samples, again, the implementation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3748) becomes a bit more complicated, as it's called N-times per transfer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3749) for each channel. See, for example, ``isa/gus/gus_pcm.c``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3750)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3751) Non-Contiguous Buffers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3752) ----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3753)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3754) If your hardware supports the page table as in emu10k1 or the buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3755) descriptors as in via82xx, you can use the scatter-gather (SG) DMA. ALSA
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3756) provides an interface for handling SG-buffers. The API is provided in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3757) ``<sound/pcm.h>``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3758)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3759) For creating the SG-buffer handler, call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3760) :c:func:`snd_pcm_set_managed_buffer()` or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3761) :c:func:`snd_pcm_set_managed_buffer_all()` with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3762) ``SNDRV_DMA_TYPE_DEV_SG`` in the PCM constructor like other PCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3763) pre-allocator. You need to pass ``&pci->dev``, where pci is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3764) the struct pci_dev pointer of the chip as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3765) well.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3766)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3767) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3768)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3769) snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV_SG,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3770) &pci->dev, size, max);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3771)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3772) The ``struct snd_sg_buf`` instance is created as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3773) ``substream->dma_private`` in turn. You can cast the pointer like:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3774)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3775) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3776)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3777) struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3778)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3779) Then in :c:func:`snd_pcm_lib_malloc_pages()` call, the common SG-buffer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3780) handler will allocate the non-contiguous kernel pages of the given size
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3781) and map them onto the virtually contiguous memory. The virtual pointer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3782) is addressed in runtime->dma_area. The physical address
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3783) (``runtime->dma_addr``) is set to zero, because the buffer is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3784) physically non-contiguous. The physical address table is set up in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3785) ``sgbuf->table``. You can get the physical address at a certain offset
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3786) via :c:func:`snd_pcm_sgbuf_get_addr()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3787)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3788) If you need to release the SG-buffer data explicitly, call the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3789) standard API function :c:func:`snd_pcm_lib_free_pages()` as usual.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3790)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3791) Vmalloc'ed Buffers
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3792) ------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3793)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3794) It's possible to use a buffer allocated via :c:func:`vmalloc()`, for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3795) example, for an intermediate buffer. In the recent version of kernel,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3796) you can simply allocate it via standard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3797) :c:func:`snd_pcm_lib_malloc_pages()` and co after setting up the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3798) buffer preallocation with ``SNDRV_DMA_TYPE_VMALLOC`` type.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3799)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3800) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3801)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3802) snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_VMALLOC,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3803) NULL, 0, 0);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3804)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3805) The NULL is passed to the device pointer argument, which indicates
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3806) that the default pages (GFP_KERNEL and GFP_HIGHMEM) will be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3807) allocated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3808)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3809) Also, note that zero is passed to both the size and the max size
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3810) arguments here. Since each vmalloc call should succeed at any time,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3811) we don't need to pre-allocate the buffers like other continuous
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3812) pages.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3813)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3814) If you need the 32bit DMA allocation, pass the device pointer encoded
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3815) by :c:func:`snd_dma_continuous_data()` with ``GFP_KERNEL|__GFP_DMA32``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3816) argument.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3817)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3818) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3819)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3820) snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_VMALLOC,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3821) snd_dma_continuous_data(GFP_KERNEL | __GFP_DMA32), 0, 0);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3822)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3823) Proc Interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3824) ==============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3825)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3826) ALSA provides an easy interface for procfs. The proc files are very
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3827) useful for debugging. I recommend you set up proc files if you write a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3828) driver and want to get a running status or register dumps. The API is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3829) found in ``<sound/info.h>``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3830)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3831) To create a proc file, call :c:func:`snd_card_proc_new()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3832)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3833) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3834)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3835) struct snd_info_entry *entry;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3836) int err = snd_card_proc_new(card, "my-file", &entry);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3837)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3838) where the second argument specifies the name of the proc file to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3839) created. The above example will create a file ``my-file`` under the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3840) card directory, e.g. ``/proc/asound/card0/my-file``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3841)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3842) Like other components, the proc entry created via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3843) :c:func:`snd_card_proc_new()` will be registered and released
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3844) automatically in the card registration and release functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3845)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3846) When the creation is successful, the function stores a new instance in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3847) the pointer given in the third argument. It is initialized as a text
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3848) proc file for read only. To use this proc file as a read-only text file
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3849) as it is, set the read callback with a private data via
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3850) :c:func:`snd_info_set_text_ops()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3851)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3852) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3853)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3854) snd_info_set_text_ops(entry, chip, my_proc_read);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3855)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3856) where the second argument (``chip``) is the private data to be used in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3857) the callbacks. The third parameter specifies the read buffer size and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3858) the fourth (``my_proc_read``) is the callback function, which is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3859) defined like
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3860)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3861) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3862)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3863) static void my_proc_read(struct snd_info_entry *entry,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3864) struct snd_info_buffer *buffer);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3865)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3866) In the read callback, use :c:func:`snd_iprintf()` for output
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3867) strings, which works just like normal :c:func:`printf()`. For
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3868) example,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3869)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3870) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3871)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3872) static void my_proc_read(struct snd_info_entry *entry,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3873) struct snd_info_buffer *buffer)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3874) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3875) struct my_chip *chip = entry->private_data;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3876)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3877) snd_iprintf(buffer, "This is my chip!\n");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3878) snd_iprintf(buffer, "Port = %ld\n", chip->port);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3879) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3880)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3881) The file permissions can be changed afterwards. As default, it's set as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3882) read only for all users. If you want to add write permission for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3883) user (root as default), do as follows:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3884)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3885) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3886)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3887) entry->mode = S_IFREG | S_IRUGO | S_IWUSR;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3888)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3889) and set the write buffer size and the callback
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3890)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3891) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3892)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3893) entry->c.text.write = my_proc_write;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3894)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3895) For the write callback, you can use :c:func:`snd_info_get_line()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3896) to get a text line, and :c:func:`snd_info_get_str()` to retrieve
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3897) a string from the line. Some examples are found in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3898) ``core/oss/mixer_oss.c``, core/oss/and ``pcm_oss.c``.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3899)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3900) For a raw-data proc-file, set the attributes as follows:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3901)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3902) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3903)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3904) static const struct snd_info_entry_ops my_file_io_ops = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3905) .read = my_file_io_read,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3906) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3907)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3908) entry->content = SNDRV_INFO_CONTENT_DATA;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3909) entry->private_data = chip;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3910) entry->c.ops = &my_file_io_ops;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3911) entry->size = 4096;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3912) entry->mode = S_IFREG | S_IRUGO;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3913)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3914) For the raw data, ``size`` field must be set properly. This specifies
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3915) the maximum size of the proc file access.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3916)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3917) The read/write callbacks of raw mode are more direct than the text mode.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3918) You need to use a low-level I/O functions such as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3919) :c:func:`copy_from_user()` and :c:func:`copy_to_user()` to transfer the data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3920)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3921) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3922)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3923) static ssize_t my_file_io_read(struct snd_info_entry *entry,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3924) void *file_private_data,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3925) struct file *file,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3926) char *buf,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3927) size_t count,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3928) loff_t pos)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3929) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3930) if (copy_to_user(buf, local_data + pos, count))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3931) return -EFAULT;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3932) return count;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3933) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3934)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3935) If the size of the info entry has been set up properly, ``count`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3936) ``pos`` are guaranteed to fit within 0 and the given size. You don't
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3937) have to check the range in the callbacks unless any other condition is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3938) required.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3939)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3940) Power Management
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3941) ================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3942)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3943) If the chip is supposed to work with suspend/resume functions, you need
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3944) to add power-management code to the driver. The additional code for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3945) power-management should be ifdef-ed with ``CONFIG_PM``, or annotated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3946) with __maybe_unused attribute; otherwise the compiler will complain
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3947) you.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3948)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3949) If the driver *fully* supports suspend/resume that is, the device can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3950) properly resumed to its state when suspend was called, you can set the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3951) ``SNDRV_PCM_INFO_RESUME`` flag in the pcm info field. Usually, this is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3952) possible when the registers of the chip can be safely saved and restored
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3953) to RAM. If this is set, the trigger callback is called with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3954) ``SNDRV_PCM_TRIGGER_RESUME`` after the resume callback completes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3955)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3956) Even if the driver doesn't support PM fully but partial suspend/resume
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3957) is still possible, it's still worthy to implement suspend/resume
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3958) callbacks. In such a case, applications would reset the status by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3959) calling :c:func:`snd_pcm_prepare()` and restart the stream
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3960) appropriately. Hence, you can define suspend/resume callbacks below but
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3961) don't set ``SNDRV_PCM_INFO_RESUME`` info flag to the PCM.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3962)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3963) Note that the trigger with SUSPEND can always be called when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3964) :c:func:`snd_pcm_suspend_all()` is called, regardless of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3965) ``SNDRV_PCM_INFO_RESUME`` flag. The ``RESUME`` flag affects only the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3966) behavior of :c:func:`snd_pcm_resume()`. (Thus, in theory,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3967) ``SNDRV_PCM_TRIGGER_RESUME`` isn't needed to be handled in the trigger
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3968) callback when no ``SNDRV_PCM_INFO_RESUME`` flag is set. But, it's better
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3969) to keep it for compatibility reasons.)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3970)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3971) In the earlier version of ALSA drivers, a common power-management layer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3972) was provided, but it has been removed. The driver needs to define the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3973) suspend/resume hooks according to the bus the device is connected to. In
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3974) the case of PCI drivers, the callbacks look like below:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3975)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3976) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3977)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3978) static int __maybe_unused snd_my_suspend(struct device *dev)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3979) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3980) .... /* do things for suspend */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3981) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3982) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3983) static int __maybe_unused snd_my_resume(struct device *dev)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3984) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3985) .... /* do things for suspend */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3986) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3987) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3988)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3989) The scheme of the real suspend job is as follows.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3990)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3991) 1. Retrieve the card and the chip data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3992)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3993) 2. Call :c:func:`snd_power_change_state()` with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3994) ``SNDRV_CTL_POWER_D3hot`` to change the power status.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3995)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3996) 3. If AC97 codecs are used, call :c:func:`snd_ac97_suspend()` for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3997) each codec.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3998)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3999) 4. Save the register values if necessary.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4000)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4001) 5. Stop the hardware if necessary.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4002)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4003) A typical code would be like:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4004)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4005) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4006)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4007) static int __maybe_unused mychip_suspend(struct device *dev)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4008) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4009) /* (1) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4010) struct snd_card *card = dev_get_drvdata(dev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4011) struct mychip *chip = card->private_data;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4012) /* (2) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4013) snd_power_change_state(card, SNDRV_CTL_POWER_D3hot);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4014) /* (3) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4015) snd_ac97_suspend(chip->ac97);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4016) /* (4) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4017) snd_mychip_save_registers(chip);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4018) /* (5) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4019) snd_mychip_stop_hardware(chip);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4020) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4021) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4022)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4023)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4024) The scheme of the real resume job is as follows.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4025)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4026) 1. Retrieve the card and the chip data.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4027)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4028) 2. Re-initialize the chip.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4029)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4030) 3. Restore the saved registers if necessary.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4031)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4032) 4. Resume the mixer, e.g. calling :c:func:`snd_ac97_resume()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4033)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4034) 5. Restart the hardware (if any).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4035)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4036) 6. Call :c:func:`snd_power_change_state()` with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4037) ``SNDRV_CTL_POWER_D0`` to notify the processes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4038)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4039) A typical code would be like:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4040)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4041) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4042)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4043) static int __maybe_unused mychip_resume(struct pci_dev *pci)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4044) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4045) /* (1) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4046) struct snd_card *card = dev_get_drvdata(dev);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4047) struct mychip *chip = card->private_data;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4048) /* (2) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4049) snd_mychip_reinit_chip(chip);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4050) /* (3) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4051) snd_mychip_restore_registers(chip);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4052) /* (4) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4053) snd_ac97_resume(chip->ac97);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4054) /* (5) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4055) snd_mychip_restart_chip(chip);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4056) /* (6) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4057) snd_power_change_state(card, SNDRV_CTL_POWER_D0);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4058) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4059) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4060)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4061) Note that, at the time this callback gets called, the PCM stream has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4062) been already suspended via its own PM ops calling
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4063) :c:func:`snd_pcm_suspend_all()` internally.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4064)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4065) OK, we have all callbacks now. Let's set them up. In the initialization
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4066) of the card, make sure that you can get the chip data from the card
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4067) instance, typically via ``private_data`` field, in case you created the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4068) chip data individually.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4069)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4070) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4071)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4072) static int snd_mychip_probe(struct pci_dev *pci,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4073) const struct pci_device_id *pci_id)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4074) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4075) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4076) struct snd_card *card;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4077) struct mychip *chip;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4078) int err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4079) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4080) err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4081) 0, &card);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4082) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4083) chip = kzalloc(sizeof(*chip), GFP_KERNEL);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4084) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4085) card->private_data = chip;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4086) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4087) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4088)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4089) When you created the chip data with :c:func:`snd_card_new()`, it's
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4090) anyway accessible via ``private_data`` field.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4091)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4092) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4093)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4094) static int snd_mychip_probe(struct pci_dev *pci,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4095) const struct pci_device_id *pci_id)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4096) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4097) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4098) struct snd_card *card;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4099) struct mychip *chip;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4100) int err;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4101) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4102) err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4103) sizeof(struct mychip), &card);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4104) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4105) chip = card->private_data;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4106) ....
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4107) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4108)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4109) If you need a space to save the registers, allocate the buffer for it
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4110) here, too, since it would be fatal if you cannot allocate a memory in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4111) the suspend phase. The allocated buffer should be released in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4112) corresponding destructor.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4114) And next, set suspend/resume callbacks to the pci_driver.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4115)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4116) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4118) static SIMPLE_DEV_PM_OPS(snd_my_pm_ops, mychip_suspend, mychip_resume);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4119)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4120) static struct pci_driver driver = {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4121) .name = KBUILD_MODNAME,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4122) .id_table = snd_my_ids,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4123) .probe = snd_my_probe,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4124) .remove = snd_my_remove,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4125) .driver.pm = &snd_my_pm_ops,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4126) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4127)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4128) Module Parameters
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4129) =================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4130)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4131) There are standard module options for ALSA. At least, each module should
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4132) have the ``index``, ``id`` and ``enable`` options.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4133)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4134) If the module supports multiple cards (usually up to 8 = ``SNDRV_CARDS``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4135) cards), they should be arrays. The default initial values are defined
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4136) already as constants for easier programming:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4137)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4138) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4139)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4140) static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4141) static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4142) static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4143)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4144) If the module supports only a single card, they could be single
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4145) variables, instead. ``enable`` option is not always necessary in this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4146) case, but it would be better to have a dummy option for compatibility.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4147)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4148) The module parameters must be declared with the standard
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4149) ``module_param()``, ``module_param_array()`` and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4150) :c:func:`MODULE_PARM_DESC()` macros.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4151)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4152) The typical coding would be like below:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4153)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4154) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4155)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4156) #define CARD_NAME "My Chip"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4157)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4158) module_param_array(index, int, NULL, 0444);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4159) MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard.");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4160) module_param_array(id, charp, NULL, 0444);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4161) MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard.");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4162) module_param_array(enable, bool, NULL, 0444);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4163) MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard.");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4164)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4165) Also, don't forget to define the module description and the license.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4166) Especially, the recent modprobe requires to define the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4167) module license as GPL, etc., otherwise the system is shown as “tainted”.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4168)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4169) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4170)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4171) MODULE_DESCRIPTION("Sound driver for My Chip");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4172) MODULE_LICENSE("GPL");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4173)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4174)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4175) How To Put Your Driver Into ALSA Tree
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4176) =====================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4177)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4178) General
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4179) -------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4180)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4181) So far, you've learned how to write the driver codes. And you might have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4182) a question now: how to put my own driver into the ALSA driver tree? Here
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4183) (finally :) the standard procedure is described briefly.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4184)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4185) Suppose that you create a new PCI driver for the card “xyz”. The card
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4186) module name would be snd-xyz. The new driver is usually put into the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4187) alsa-driver tree, ``sound/pci`` directory in the case of PCI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4188) cards.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4189)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4190) In the following sections, the driver code is supposed to be put into
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4191) Linux kernel tree. The two cases are covered: a driver consisting of a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4192) single source file and one consisting of several source files.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4193)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4194) Driver with A Single Source File
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4195) --------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4196)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4197) 1. Modify sound/pci/Makefile
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4198)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4199) Suppose you have a file xyz.c. Add the following two lines
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4200)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4201) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4202)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4203) snd-xyz-objs := xyz.o
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4204) obj-$(CONFIG_SND_XYZ) += snd-xyz.o
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4205)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4206) 2. Create the Kconfig entry
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4207)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4208) Add the new entry of Kconfig for your xyz driver. config SND_XYZ
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4209) tristate "Foobar XYZ" depends on SND select SND_PCM help Say Y here
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4210) to include support for Foobar XYZ soundcard. To compile this driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4211) as a module, choose M here: the module will be called snd-xyz. the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4212) line, select SND_PCM, specifies that the driver xyz supports PCM. In
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4213) addition to SND_PCM, the following components are supported for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4214) select command: SND_RAWMIDI, SND_TIMER, SND_HWDEP,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4215) SND_MPU401_UART, SND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4216) SND_AC97_CODEC. Add the select command for each supported
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4217) component.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4218)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4219) Note that some selections imply the lowlevel selections. For example,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4220) PCM includes TIMER, MPU401_UART includes RAWMIDI, AC97_CODEC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4221) includes PCM, and OPL3_LIB includes HWDEP. You don't need to give
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4222) the lowlevel selections again.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4223)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4224) For the details of Kconfig script, refer to the kbuild documentation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4225)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4226) Drivers with Several Source Files
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4227) ---------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4228)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4229) Suppose that the driver snd-xyz have several source files. They are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4230) located in the new subdirectory, sound/pci/xyz.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4231)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4232) 1. Add a new directory (``sound/pci/xyz``) in ``sound/pci/Makefile``
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4233) as below
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4234)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4235) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4236)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4237) obj-$(CONFIG_SND) += sound/pci/xyz/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4238)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4239)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4240) 2. Under the directory ``sound/pci/xyz``, create a Makefile
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4241)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4242) ::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4243)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4244) snd-xyz-objs := xyz.o abc.o def.o
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4245) obj-$(CONFIG_SND_XYZ) += snd-xyz.o
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4246)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4247) 3. Create the Kconfig entry
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4248)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4249) This procedure is as same as in the last section.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4250)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4251)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4252) Useful Functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4253) ================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4254)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4255) :c:func:`snd_printk()` and friends
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4256) ----------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4257)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4258) .. note:: This subsection describes a few helper functions for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4259) decorating a bit more on the standard :c:func:`printk()` & co.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4260) However, in general, the use of such helpers is no longer recommended.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4261) If possible, try to stick with the standard functions like
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4262) :c:func:`dev_err()` or :c:func:`pr_err()`.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4263)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4264) ALSA provides a verbose version of the :c:func:`printk()` function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4265) If a kernel config ``CONFIG_SND_VERBOSE_PRINTK`` is set, this function
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4266) prints the given message together with the file name and the line of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4267) caller. The ``KERN_XXX`` prefix is processed as well as the original
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4268) :c:func:`printk()` does, so it's recommended to add this prefix,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4269) e.g. snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\\n");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4270)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4271) There are also :c:func:`printk()`'s for debugging.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4272) :c:func:`snd_printd()` can be used for general debugging purposes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4273) If ``CONFIG_SND_DEBUG`` is set, this function is compiled, and works
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4274) just like :c:func:`snd_printk()`. If the ALSA is compiled without
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4275) the debugging flag, it's ignored.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4276)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4277) :c:func:`snd_printdd()` is compiled in only when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4278) ``CONFIG_SND_DEBUG_VERBOSE`` is set.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4279)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4280) :c:func:`snd_BUG()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4281) -------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4282)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4283) It shows the ``BUG?`` message and stack trace as well as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4284) :c:func:`snd_BUG_ON()` at the point. It's useful to show that a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4285) fatal error happens there.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4286)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4287) When no debug flag is set, this macro is ignored.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4288)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4289) :c:func:`snd_BUG_ON()`
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4290) ----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4291)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4292) :c:func:`snd_BUG_ON()` macro is similar with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4293) :c:func:`WARN_ON()` macro. For example, snd_BUG_ON(!pointer); or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4294) it can be used as the condition, if (snd_BUG_ON(non_zero_is_bug))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4295) return -EINVAL;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4296)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4297) The macro takes an conditional expression to evaluate. When
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4298) ``CONFIG_SND_DEBUG``, is set, if the expression is non-zero, it shows
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4299) the warning message such as ``BUG? (xxx)`` normally followed by stack
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4300) trace. In both cases it returns the evaluated value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4301)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4302) Acknowledgments
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4303) ===============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4304)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4305) I would like to thank Phil Kerr for his help for improvement and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4306) corrections of this document.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4307)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4308) Kevin Conder reformatted the original plain-text to the DocBook format.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4309)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4310) Giuliano Pochini corrected typos and contributed the example codes in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4311) the hardware constraints section.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags