162306a36Sopenharmony_ci====================== 262306a36Sopenharmony_ciWriting an ALSA Driver 362306a36Sopenharmony_ci====================== 462306a36Sopenharmony_ci 562306a36Sopenharmony_ci:Author: Takashi Iwai <tiwai@suse.de> 662306a36Sopenharmony_ci 762306a36Sopenharmony_ciPreface 862306a36Sopenharmony_ci======= 962306a36Sopenharmony_ci 1062306a36Sopenharmony_ciThis document describes how to write an `ALSA (Advanced Linux Sound 1162306a36Sopenharmony_ciArchitecture) <http://www.alsa-project.org/>`__ driver. The document 1262306a36Sopenharmony_cifocuses mainly on PCI soundcards. In the case of other device types, the 1362306a36Sopenharmony_ciAPI might be different, too. However, at least the ALSA kernel API is 1462306a36Sopenharmony_ciconsistent, and therefore it would be still a bit help for writing them. 1562306a36Sopenharmony_ci 1662306a36Sopenharmony_ciThis document targets people who already have enough C language skills 1762306a36Sopenharmony_ciand have basic linux kernel programming knowledge. This document doesn't 1862306a36Sopenharmony_ciexplain the general topic of linux kernel coding and doesn't cover 1962306a36Sopenharmony_cilow-level driver implementation details. It only describes the standard 2062306a36Sopenharmony_ciway to write a PCI sound driver on ALSA. 2162306a36Sopenharmony_ci 2262306a36Sopenharmony_ciFile Tree Structure 2362306a36Sopenharmony_ci=================== 2462306a36Sopenharmony_ci 2562306a36Sopenharmony_ciGeneral 2662306a36Sopenharmony_ci------- 2762306a36Sopenharmony_ci 2862306a36Sopenharmony_ciThe file tree structure of ALSA driver is depicted below:: 2962306a36Sopenharmony_ci 3062306a36Sopenharmony_ci sound 3162306a36Sopenharmony_ci /core 3262306a36Sopenharmony_ci /oss 3362306a36Sopenharmony_ci /seq 3462306a36Sopenharmony_ci /oss 3562306a36Sopenharmony_ci /include 3662306a36Sopenharmony_ci /drivers 3762306a36Sopenharmony_ci /mpu401 3862306a36Sopenharmony_ci /opl3 3962306a36Sopenharmony_ci /i2c 4062306a36Sopenharmony_ci /synth 4162306a36Sopenharmony_ci /emux 4262306a36Sopenharmony_ci /pci 4362306a36Sopenharmony_ci /(cards) 4462306a36Sopenharmony_ci /isa 4562306a36Sopenharmony_ci /(cards) 4662306a36Sopenharmony_ci /arm 4762306a36Sopenharmony_ci /ppc 4862306a36Sopenharmony_ci /sparc 4962306a36Sopenharmony_ci /usb 5062306a36Sopenharmony_ci /pcmcia /(cards) 5162306a36Sopenharmony_ci /soc 5262306a36Sopenharmony_ci /oss 5362306a36Sopenharmony_ci 5462306a36Sopenharmony_ci 5562306a36Sopenharmony_cicore directory 5662306a36Sopenharmony_ci-------------- 5762306a36Sopenharmony_ci 5862306a36Sopenharmony_ciThis directory contains the middle layer which is the heart of ALSA 5962306a36Sopenharmony_cidrivers. In this directory, the native ALSA modules are stored. The 6062306a36Sopenharmony_cisub-directories contain different modules and are dependent upon the 6162306a36Sopenharmony_cikernel config. 6262306a36Sopenharmony_ci 6362306a36Sopenharmony_cicore/oss 6462306a36Sopenharmony_ci~~~~~~~~ 6562306a36Sopenharmony_ci 6662306a36Sopenharmony_ciThe code for OSS PCM and mixer emulation modules is stored in this 6762306a36Sopenharmony_cidirectory. The OSS rawmidi emulation is included in the ALSA rawmidi 6862306a36Sopenharmony_cicode since it's quite small. The sequencer code is stored in 6962306a36Sopenharmony_ci``core/seq/oss`` directory (see `below <core/seq/oss_>`__). 7062306a36Sopenharmony_ci 7162306a36Sopenharmony_cicore/seq 7262306a36Sopenharmony_ci~~~~~~~~ 7362306a36Sopenharmony_ci 7462306a36Sopenharmony_ciThis directory and its sub-directories are for the ALSA sequencer. This 7562306a36Sopenharmony_cidirectory contains the sequencer core and primary sequencer modules such 7662306a36Sopenharmony_cias snd-seq-midi, snd-seq-virmidi, etc. They are compiled only when 7762306a36Sopenharmony_ci``CONFIG_SND_SEQUENCER`` is set in the kernel config. 7862306a36Sopenharmony_ci 7962306a36Sopenharmony_cicore/seq/oss 8062306a36Sopenharmony_ci~~~~~~~~~~~~ 8162306a36Sopenharmony_ci 8262306a36Sopenharmony_ciThis contains the OSS sequencer emulation code. 8362306a36Sopenharmony_ci 8462306a36Sopenharmony_ciinclude directory 8562306a36Sopenharmony_ci----------------- 8662306a36Sopenharmony_ci 8762306a36Sopenharmony_ciThis is the place for the public header files of ALSA drivers, which are 8862306a36Sopenharmony_cito be exported to user-space, or included by several files in different 8962306a36Sopenharmony_cidirectories. Basically, the private header files should not be placed in 9062306a36Sopenharmony_cithis directory, but you may still find files there, due to historical 9162306a36Sopenharmony_cireasons :) 9262306a36Sopenharmony_ci 9362306a36Sopenharmony_cidrivers directory 9462306a36Sopenharmony_ci----------------- 9562306a36Sopenharmony_ci 9662306a36Sopenharmony_ciThis directory contains code shared among different drivers on different 9762306a36Sopenharmony_ciarchitectures. They are hence supposed not to be architecture-specific. 9862306a36Sopenharmony_ciFor example, the dummy PCM driver and the serial MIDI driver are found 9962306a36Sopenharmony_ciin this directory. In the sub-directories, there is code for components 10062306a36Sopenharmony_ciwhich are independent from bus and cpu architectures. 10162306a36Sopenharmony_ci 10262306a36Sopenharmony_cidrivers/mpu401 10362306a36Sopenharmony_ci~~~~~~~~~~~~~~ 10462306a36Sopenharmony_ci 10562306a36Sopenharmony_ciThe MPU401 and MPU401-UART modules are stored here. 10662306a36Sopenharmony_ci 10762306a36Sopenharmony_cidrivers/opl3 and opl4 10862306a36Sopenharmony_ci~~~~~~~~~~~~~~~~~~~~~ 10962306a36Sopenharmony_ci 11062306a36Sopenharmony_ciThe OPL3 and OPL4 FM-synth stuff is found here. 11162306a36Sopenharmony_ci 11262306a36Sopenharmony_cii2c directory 11362306a36Sopenharmony_ci------------- 11462306a36Sopenharmony_ci 11562306a36Sopenharmony_ciThis contains the ALSA i2c components. 11662306a36Sopenharmony_ci 11762306a36Sopenharmony_ciAlthough there is a standard i2c layer on Linux, ALSA has its own i2c 11862306a36Sopenharmony_cicode for some cards, because the soundcard needs only a simple operation 11962306a36Sopenharmony_ciand the standard i2c API is too complicated for such a purpose. 12062306a36Sopenharmony_ci 12162306a36Sopenharmony_cisynth directory 12262306a36Sopenharmony_ci--------------- 12362306a36Sopenharmony_ci 12462306a36Sopenharmony_ciThis contains the synth middle-level modules. 12562306a36Sopenharmony_ci 12662306a36Sopenharmony_ciSo far, there is only Emu8000/Emu10k1 synth driver under the 12762306a36Sopenharmony_ci``synth/emux`` sub-directory. 12862306a36Sopenharmony_ci 12962306a36Sopenharmony_cipci directory 13062306a36Sopenharmony_ci------------- 13162306a36Sopenharmony_ci 13262306a36Sopenharmony_ciThis directory and its sub-directories hold the top-level card modules 13362306a36Sopenharmony_cifor PCI soundcards and the code specific to the PCI BUS. 13462306a36Sopenharmony_ci 13562306a36Sopenharmony_ciThe drivers compiled from a single file are stored directly in the pci 13662306a36Sopenharmony_cidirectory, while the drivers with several source files are stored on 13762306a36Sopenharmony_citheir own sub-directory (e.g. emu10k1, ice1712). 13862306a36Sopenharmony_ci 13962306a36Sopenharmony_ciisa directory 14062306a36Sopenharmony_ci------------- 14162306a36Sopenharmony_ci 14262306a36Sopenharmony_ciThis directory and its sub-directories hold the top-level card modules 14362306a36Sopenharmony_cifor ISA soundcards. 14462306a36Sopenharmony_ci 14562306a36Sopenharmony_ciarm, ppc, and sparc directories 14662306a36Sopenharmony_ci------------------------------- 14762306a36Sopenharmony_ci 14862306a36Sopenharmony_ciThey are used for top-level card modules which are specific to one of 14962306a36Sopenharmony_cithese architectures. 15062306a36Sopenharmony_ci 15162306a36Sopenharmony_ciusb directory 15262306a36Sopenharmony_ci------------- 15362306a36Sopenharmony_ci 15462306a36Sopenharmony_ciThis directory contains the USB-audio driver. 15562306a36Sopenharmony_ciThe USB MIDI driver is integrated in the usb-audio driver. 15662306a36Sopenharmony_ci 15762306a36Sopenharmony_cipcmcia directory 15862306a36Sopenharmony_ci---------------- 15962306a36Sopenharmony_ci 16062306a36Sopenharmony_ciThe PCMCIA, especially PCCard drivers will go here. CardBus drivers will 16162306a36Sopenharmony_cibe in the pci directory, because their API is identical to that of 16262306a36Sopenharmony_cistandard PCI cards. 16362306a36Sopenharmony_ci 16462306a36Sopenharmony_cisoc directory 16562306a36Sopenharmony_ci------------- 16662306a36Sopenharmony_ci 16762306a36Sopenharmony_ciThis directory contains the codes for ASoC (ALSA System on Chip) 16862306a36Sopenharmony_cilayer including ASoC core, codec and machine drivers. 16962306a36Sopenharmony_ci 17062306a36Sopenharmony_cioss directory 17162306a36Sopenharmony_ci------------- 17262306a36Sopenharmony_ci 17362306a36Sopenharmony_ciThis contains OSS/Lite code. 17462306a36Sopenharmony_ciAt the time of writing, all code has been removed except for dmasound 17562306a36Sopenharmony_cion m68k. 17662306a36Sopenharmony_ci 17762306a36Sopenharmony_ci 17862306a36Sopenharmony_ciBasic Flow for PCI Drivers 17962306a36Sopenharmony_ci========================== 18062306a36Sopenharmony_ci 18162306a36Sopenharmony_ciOutline 18262306a36Sopenharmony_ci------- 18362306a36Sopenharmony_ci 18462306a36Sopenharmony_ciThe minimum flow for PCI soundcards is as follows: 18562306a36Sopenharmony_ci 18662306a36Sopenharmony_ci- define the PCI ID table (see the section `PCI Entries`_). 18762306a36Sopenharmony_ci 18862306a36Sopenharmony_ci- create ``probe`` callback. 18962306a36Sopenharmony_ci 19062306a36Sopenharmony_ci- create ``remove`` callback. 19162306a36Sopenharmony_ci 19262306a36Sopenharmony_ci- create a struct pci_driver structure 19362306a36Sopenharmony_ci containing the three pointers above. 19462306a36Sopenharmony_ci 19562306a36Sopenharmony_ci- create an ``init`` function just calling the 19662306a36Sopenharmony_ci :c:func:`pci_register_driver()` to register the pci_driver 19762306a36Sopenharmony_ci table defined above. 19862306a36Sopenharmony_ci 19962306a36Sopenharmony_ci- create an ``exit`` function to call the 20062306a36Sopenharmony_ci :c:func:`pci_unregister_driver()` function. 20162306a36Sopenharmony_ci 20262306a36Sopenharmony_ciFull Code Example 20362306a36Sopenharmony_ci----------------- 20462306a36Sopenharmony_ci 20562306a36Sopenharmony_ciThe code example is shown below. Some parts are kept unimplemented at 20662306a36Sopenharmony_cithis moment but will be filled in the next sections. The numbers in the 20762306a36Sopenharmony_cicomment lines of the :c:func:`snd_mychip_probe()` function refer 20862306a36Sopenharmony_cito details explained in the following section. 20962306a36Sopenharmony_ci 21062306a36Sopenharmony_ci:: 21162306a36Sopenharmony_ci 21262306a36Sopenharmony_ci #include <linux/init.h> 21362306a36Sopenharmony_ci #include <linux/pci.h> 21462306a36Sopenharmony_ci #include <linux/slab.h> 21562306a36Sopenharmony_ci #include <sound/core.h> 21662306a36Sopenharmony_ci #include <sound/initval.h> 21762306a36Sopenharmony_ci 21862306a36Sopenharmony_ci /* module parameters (see "Module Parameters") */ 21962306a36Sopenharmony_ci /* SNDRV_CARDS: maximum number of cards supported by this module */ 22062306a36Sopenharmony_ci static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX; 22162306a36Sopenharmony_ci static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR; 22262306a36Sopenharmony_ci static bool enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP; 22362306a36Sopenharmony_ci 22462306a36Sopenharmony_ci /* definition of the chip-specific record */ 22562306a36Sopenharmony_ci struct mychip { 22662306a36Sopenharmony_ci struct snd_card *card; 22762306a36Sopenharmony_ci /* the rest of the implementation will be in section 22862306a36Sopenharmony_ci * "PCI Resource Management" 22962306a36Sopenharmony_ci */ 23062306a36Sopenharmony_ci }; 23162306a36Sopenharmony_ci 23262306a36Sopenharmony_ci /* chip-specific destructor 23362306a36Sopenharmony_ci * (see "PCI Resource Management") 23462306a36Sopenharmony_ci */ 23562306a36Sopenharmony_ci static int snd_mychip_free(struct mychip *chip) 23662306a36Sopenharmony_ci { 23762306a36Sopenharmony_ci .... /* will be implemented later... */ 23862306a36Sopenharmony_ci } 23962306a36Sopenharmony_ci 24062306a36Sopenharmony_ci /* component-destructor 24162306a36Sopenharmony_ci * (see "Management of Cards and Components") 24262306a36Sopenharmony_ci */ 24362306a36Sopenharmony_ci static int snd_mychip_dev_free(struct snd_device *device) 24462306a36Sopenharmony_ci { 24562306a36Sopenharmony_ci return snd_mychip_free(device->device_data); 24662306a36Sopenharmony_ci } 24762306a36Sopenharmony_ci 24862306a36Sopenharmony_ci /* chip-specific constructor 24962306a36Sopenharmony_ci * (see "Management of Cards and Components") 25062306a36Sopenharmony_ci */ 25162306a36Sopenharmony_ci static int snd_mychip_create(struct snd_card *card, 25262306a36Sopenharmony_ci struct pci_dev *pci, 25362306a36Sopenharmony_ci struct mychip **rchip) 25462306a36Sopenharmony_ci { 25562306a36Sopenharmony_ci struct mychip *chip; 25662306a36Sopenharmony_ci int err; 25762306a36Sopenharmony_ci static const struct snd_device_ops ops = { 25862306a36Sopenharmony_ci .dev_free = snd_mychip_dev_free, 25962306a36Sopenharmony_ci }; 26062306a36Sopenharmony_ci 26162306a36Sopenharmony_ci *rchip = NULL; 26262306a36Sopenharmony_ci 26362306a36Sopenharmony_ci /* check PCI availability here 26462306a36Sopenharmony_ci * (see "PCI Resource Management") 26562306a36Sopenharmony_ci */ 26662306a36Sopenharmony_ci .... 26762306a36Sopenharmony_ci 26862306a36Sopenharmony_ci /* allocate a chip-specific data with zero filled */ 26962306a36Sopenharmony_ci chip = kzalloc(sizeof(*chip), GFP_KERNEL); 27062306a36Sopenharmony_ci if (chip == NULL) 27162306a36Sopenharmony_ci return -ENOMEM; 27262306a36Sopenharmony_ci 27362306a36Sopenharmony_ci chip->card = card; 27462306a36Sopenharmony_ci 27562306a36Sopenharmony_ci /* rest of initialization here; will be implemented 27662306a36Sopenharmony_ci * later, see "PCI Resource Management" 27762306a36Sopenharmony_ci */ 27862306a36Sopenharmony_ci .... 27962306a36Sopenharmony_ci 28062306a36Sopenharmony_ci err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops); 28162306a36Sopenharmony_ci if (err < 0) { 28262306a36Sopenharmony_ci snd_mychip_free(chip); 28362306a36Sopenharmony_ci return err; 28462306a36Sopenharmony_ci } 28562306a36Sopenharmony_ci 28662306a36Sopenharmony_ci *rchip = chip; 28762306a36Sopenharmony_ci return 0; 28862306a36Sopenharmony_ci } 28962306a36Sopenharmony_ci 29062306a36Sopenharmony_ci /* constructor -- see "Driver Constructor" sub-section */ 29162306a36Sopenharmony_ci static int snd_mychip_probe(struct pci_dev *pci, 29262306a36Sopenharmony_ci const struct pci_device_id *pci_id) 29362306a36Sopenharmony_ci { 29462306a36Sopenharmony_ci static int dev; 29562306a36Sopenharmony_ci struct snd_card *card; 29662306a36Sopenharmony_ci struct mychip *chip; 29762306a36Sopenharmony_ci int err; 29862306a36Sopenharmony_ci 29962306a36Sopenharmony_ci /* (1) */ 30062306a36Sopenharmony_ci if (dev >= SNDRV_CARDS) 30162306a36Sopenharmony_ci return -ENODEV; 30262306a36Sopenharmony_ci if (!enable[dev]) { 30362306a36Sopenharmony_ci dev++; 30462306a36Sopenharmony_ci return -ENOENT; 30562306a36Sopenharmony_ci } 30662306a36Sopenharmony_ci 30762306a36Sopenharmony_ci /* (2) */ 30862306a36Sopenharmony_ci err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, 30962306a36Sopenharmony_ci 0, &card); 31062306a36Sopenharmony_ci if (err < 0) 31162306a36Sopenharmony_ci return err; 31262306a36Sopenharmony_ci 31362306a36Sopenharmony_ci /* (3) */ 31462306a36Sopenharmony_ci err = snd_mychip_create(card, pci, &chip); 31562306a36Sopenharmony_ci if (err < 0) 31662306a36Sopenharmony_ci goto error; 31762306a36Sopenharmony_ci 31862306a36Sopenharmony_ci /* (4) */ 31962306a36Sopenharmony_ci strcpy(card->driver, "My Chip"); 32062306a36Sopenharmony_ci strcpy(card->shortname, "My Own Chip 123"); 32162306a36Sopenharmony_ci sprintf(card->longname, "%s at 0x%lx irq %i", 32262306a36Sopenharmony_ci card->shortname, chip->port, chip->irq); 32362306a36Sopenharmony_ci 32462306a36Sopenharmony_ci /* (5) */ 32562306a36Sopenharmony_ci .... /* implemented later */ 32662306a36Sopenharmony_ci 32762306a36Sopenharmony_ci /* (6) */ 32862306a36Sopenharmony_ci err = snd_card_register(card); 32962306a36Sopenharmony_ci if (err < 0) 33062306a36Sopenharmony_ci goto error; 33162306a36Sopenharmony_ci 33262306a36Sopenharmony_ci /* (7) */ 33362306a36Sopenharmony_ci pci_set_drvdata(pci, card); 33462306a36Sopenharmony_ci dev++; 33562306a36Sopenharmony_ci return 0; 33662306a36Sopenharmony_ci 33762306a36Sopenharmony_ci error: 33862306a36Sopenharmony_ci snd_card_free(card); 33962306a36Sopenharmony_ci return err; 34062306a36Sopenharmony_ci } 34162306a36Sopenharmony_ci 34262306a36Sopenharmony_ci /* destructor -- see the "Destructor" sub-section */ 34362306a36Sopenharmony_ci static void snd_mychip_remove(struct pci_dev *pci) 34462306a36Sopenharmony_ci { 34562306a36Sopenharmony_ci snd_card_free(pci_get_drvdata(pci)); 34662306a36Sopenharmony_ci } 34762306a36Sopenharmony_ci 34862306a36Sopenharmony_ci 34962306a36Sopenharmony_ci 35062306a36Sopenharmony_ciDriver Constructor 35162306a36Sopenharmony_ci------------------ 35262306a36Sopenharmony_ci 35362306a36Sopenharmony_ciThe real constructor of PCI drivers is the ``probe`` callback. The 35462306a36Sopenharmony_ci``probe`` callback and other component-constructors which are called 35562306a36Sopenharmony_cifrom the ``probe`` callback cannot be used with the ``__init`` prefix 35662306a36Sopenharmony_cibecause any PCI device could be a hotplug device. 35762306a36Sopenharmony_ci 35862306a36Sopenharmony_ciIn the ``probe`` callback, the following scheme is often used. 35962306a36Sopenharmony_ci 36062306a36Sopenharmony_ci1) Check and increment the device index. 36162306a36Sopenharmony_ci~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 36262306a36Sopenharmony_ci 36362306a36Sopenharmony_ci:: 36462306a36Sopenharmony_ci 36562306a36Sopenharmony_ci static int dev; 36662306a36Sopenharmony_ci .... 36762306a36Sopenharmony_ci if (dev >= SNDRV_CARDS) 36862306a36Sopenharmony_ci return -ENODEV; 36962306a36Sopenharmony_ci if (!enable[dev]) { 37062306a36Sopenharmony_ci dev++; 37162306a36Sopenharmony_ci return -ENOENT; 37262306a36Sopenharmony_ci } 37362306a36Sopenharmony_ci 37462306a36Sopenharmony_ci 37562306a36Sopenharmony_ciwhere ``enable[dev]`` is the module option. 37662306a36Sopenharmony_ci 37762306a36Sopenharmony_ciEach time the ``probe`` callback is called, check the availability of 37862306a36Sopenharmony_cithe device. If not available, simply increment the device index and 37962306a36Sopenharmony_cireturn. dev will be incremented also later (`step 7 38062306a36Sopenharmony_ci<7) Set the PCI driver data and return zero._>`__). 38162306a36Sopenharmony_ci 38262306a36Sopenharmony_ci2) Create a card instance 38362306a36Sopenharmony_ci~~~~~~~~~~~~~~~~~~~~~~~~~ 38462306a36Sopenharmony_ci 38562306a36Sopenharmony_ci:: 38662306a36Sopenharmony_ci 38762306a36Sopenharmony_ci struct snd_card *card; 38862306a36Sopenharmony_ci int err; 38962306a36Sopenharmony_ci .... 39062306a36Sopenharmony_ci err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, 39162306a36Sopenharmony_ci 0, &card); 39262306a36Sopenharmony_ci 39362306a36Sopenharmony_ci 39462306a36Sopenharmony_ciThe details will be explained in the section `Management of Cards and 39562306a36Sopenharmony_ciComponents`_. 39662306a36Sopenharmony_ci 39762306a36Sopenharmony_ci3) Create a main component 39862306a36Sopenharmony_ci~~~~~~~~~~~~~~~~~~~~~~~~~~ 39962306a36Sopenharmony_ci 40062306a36Sopenharmony_ciIn this part, the PCI resources are allocated:: 40162306a36Sopenharmony_ci 40262306a36Sopenharmony_ci struct mychip *chip; 40362306a36Sopenharmony_ci .... 40462306a36Sopenharmony_ci err = snd_mychip_create(card, pci, &chip); 40562306a36Sopenharmony_ci if (err < 0) 40662306a36Sopenharmony_ci goto error; 40762306a36Sopenharmony_ci 40862306a36Sopenharmony_ciThe details will be explained in the section `PCI Resource 40962306a36Sopenharmony_ciManagement`_. 41062306a36Sopenharmony_ci 41162306a36Sopenharmony_ciWhen something goes wrong, the probe function needs to deal with the 41262306a36Sopenharmony_cierror. In this example, we have a single error handling path placed 41362306a36Sopenharmony_ciat the end of the function:: 41462306a36Sopenharmony_ci 41562306a36Sopenharmony_ci error: 41662306a36Sopenharmony_ci snd_card_free(card); 41762306a36Sopenharmony_ci return err; 41862306a36Sopenharmony_ci 41962306a36Sopenharmony_ciSince each component can be properly freed, the single 42062306a36Sopenharmony_ci:c:func:`snd_card_free()` call should suffice in most cases. 42162306a36Sopenharmony_ci 42262306a36Sopenharmony_ci 42362306a36Sopenharmony_ci4) Set the driver ID and name strings. 42462306a36Sopenharmony_ci~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 42562306a36Sopenharmony_ci 42662306a36Sopenharmony_ci:: 42762306a36Sopenharmony_ci 42862306a36Sopenharmony_ci strcpy(card->driver, "My Chip"); 42962306a36Sopenharmony_ci strcpy(card->shortname, "My Own Chip 123"); 43062306a36Sopenharmony_ci sprintf(card->longname, "%s at 0x%lx irq %i", 43162306a36Sopenharmony_ci card->shortname, chip->port, chip->irq); 43262306a36Sopenharmony_ci 43362306a36Sopenharmony_ciThe driver field holds the minimal ID string of the chip. This is used 43462306a36Sopenharmony_ciby alsa-lib's configurator, so keep it simple but unique. Even the 43562306a36Sopenharmony_cisame driver can have different driver IDs to distinguish the 43662306a36Sopenharmony_cifunctionality of each chip type. 43762306a36Sopenharmony_ci 43862306a36Sopenharmony_ciThe shortname field is a string shown as more verbose name. The longname 43962306a36Sopenharmony_cifield contains the information shown in ``/proc/asound/cards``. 44062306a36Sopenharmony_ci 44162306a36Sopenharmony_ci5) Create other components, such as mixer, MIDI, etc. 44262306a36Sopenharmony_ci~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 44362306a36Sopenharmony_ci 44462306a36Sopenharmony_ciHere you define the basic components such as `PCM <PCM Interface_>`__, 44562306a36Sopenharmony_cimixer (e.g. `AC97 <API for AC97 Codec_>`__), MIDI (e.g. 44662306a36Sopenharmony_ci`MPU-401 <MIDI (MPU401-UART) Interface_>`__), and other interfaces. 44762306a36Sopenharmony_ciAlso, if you want a `proc file <Proc Interface_>`__, define it here, 44862306a36Sopenharmony_citoo. 44962306a36Sopenharmony_ci 45062306a36Sopenharmony_ci6) Register the card instance. 45162306a36Sopenharmony_ci~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 45262306a36Sopenharmony_ci 45362306a36Sopenharmony_ci:: 45462306a36Sopenharmony_ci 45562306a36Sopenharmony_ci err = snd_card_register(card); 45662306a36Sopenharmony_ci if (err < 0) 45762306a36Sopenharmony_ci goto error; 45862306a36Sopenharmony_ci 45962306a36Sopenharmony_ciWill be explained in the section `Management of Cards and 46062306a36Sopenharmony_ciComponents`_, too. 46162306a36Sopenharmony_ci 46262306a36Sopenharmony_ci7) Set the PCI driver data and return zero. 46362306a36Sopenharmony_ci~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 46462306a36Sopenharmony_ci 46562306a36Sopenharmony_ci:: 46662306a36Sopenharmony_ci 46762306a36Sopenharmony_ci pci_set_drvdata(pci, card); 46862306a36Sopenharmony_ci dev++; 46962306a36Sopenharmony_ci return 0; 47062306a36Sopenharmony_ci 47162306a36Sopenharmony_ciIn the above, the card record is stored. This pointer is used in the 47262306a36Sopenharmony_ciremove callback and power-management callbacks, too. 47362306a36Sopenharmony_ci 47462306a36Sopenharmony_ciDestructor 47562306a36Sopenharmony_ci---------- 47662306a36Sopenharmony_ci 47762306a36Sopenharmony_ciThe destructor, the remove callback, simply releases the card instance. 47862306a36Sopenharmony_ciThen the ALSA middle layer will release all the attached components 47962306a36Sopenharmony_ciautomatically. 48062306a36Sopenharmony_ci 48162306a36Sopenharmony_ciIt would be typically just calling :c:func:`snd_card_free()`:: 48262306a36Sopenharmony_ci 48362306a36Sopenharmony_ci static void snd_mychip_remove(struct pci_dev *pci) 48462306a36Sopenharmony_ci { 48562306a36Sopenharmony_ci snd_card_free(pci_get_drvdata(pci)); 48662306a36Sopenharmony_ci } 48762306a36Sopenharmony_ci 48862306a36Sopenharmony_ci 48962306a36Sopenharmony_ciThe above code assumes that the card pointer is set to the PCI driver 49062306a36Sopenharmony_cidata. 49162306a36Sopenharmony_ci 49262306a36Sopenharmony_ciHeader Files 49362306a36Sopenharmony_ci------------ 49462306a36Sopenharmony_ci 49562306a36Sopenharmony_ciFor the above example, at least the following include files are 49662306a36Sopenharmony_cinecessary:: 49762306a36Sopenharmony_ci 49862306a36Sopenharmony_ci #include <linux/init.h> 49962306a36Sopenharmony_ci #include <linux/pci.h> 50062306a36Sopenharmony_ci #include <linux/slab.h> 50162306a36Sopenharmony_ci #include <sound/core.h> 50262306a36Sopenharmony_ci #include <sound/initval.h> 50362306a36Sopenharmony_ci 50462306a36Sopenharmony_ciwhere the last one is necessary only when module options are defined 50562306a36Sopenharmony_ciin the source file. If the code is split into several files, the files 50662306a36Sopenharmony_ciwithout module options don't need them. 50762306a36Sopenharmony_ci 50862306a36Sopenharmony_ciIn addition to these headers, you'll need ``<linux/interrupt.h>`` for 50962306a36Sopenharmony_ciinterrupt handling, and ``<linux/io.h>`` for I/O access. If you use the 51062306a36Sopenharmony_ci:c:func:`mdelay()` or :c:func:`udelay()` functions, you'll need 51162306a36Sopenharmony_cito include ``<linux/delay.h>`` too. 51262306a36Sopenharmony_ci 51362306a36Sopenharmony_ciThe ALSA interfaces like the PCM and control APIs are defined in other 51462306a36Sopenharmony_ci``<sound/xxx.h>`` header files. They have to be included after 51562306a36Sopenharmony_ci``<sound/core.h>``. 51662306a36Sopenharmony_ci 51762306a36Sopenharmony_ciManagement of Cards and Components 51862306a36Sopenharmony_ci================================== 51962306a36Sopenharmony_ci 52062306a36Sopenharmony_ciCard Instance 52162306a36Sopenharmony_ci------------- 52262306a36Sopenharmony_ci 52362306a36Sopenharmony_ciFor each soundcard, a “card” record must be allocated. 52462306a36Sopenharmony_ci 52562306a36Sopenharmony_ciA card record is the headquarters of the soundcard. It manages the whole 52662306a36Sopenharmony_cilist of devices (components) on the soundcard, such as PCM, mixers, 52762306a36Sopenharmony_ciMIDI, synthesizer, and so on. Also, the card record holds the ID and the 52862306a36Sopenharmony_ciname strings of the card, manages the root of proc files, and controls 52962306a36Sopenharmony_cithe power-management states and hotplug disconnections. The component 53062306a36Sopenharmony_cilist on the card record is used to manage the correct release of 53162306a36Sopenharmony_ciresources at destruction. 53262306a36Sopenharmony_ci 53362306a36Sopenharmony_ciAs mentioned above, to create a card instance, call 53462306a36Sopenharmony_ci:c:func:`snd_card_new()`:: 53562306a36Sopenharmony_ci 53662306a36Sopenharmony_ci struct snd_card *card; 53762306a36Sopenharmony_ci int err; 53862306a36Sopenharmony_ci err = snd_card_new(&pci->dev, index, id, module, extra_size, &card); 53962306a36Sopenharmony_ci 54062306a36Sopenharmony_ci 54162306a36Sopenharmony_ciThe function takes six arguments: the parent device pointer, the 54262306a36Sopenharmony_cicard-index number, the id string, the module pointer (usually 54362306a36Sopenharmony_ci``THIS_MODULE``), the size of extra-data space, and the pointer to 54462306a36Sopenharmony_cireturn the card instance. The extra_size argument is used to allocate 54562306a36Sopenharmony_cicard->private_data for the chip-specific data. Note that these data are 54662306a36Sopenharmony_ciallocated by :c:func:`snd_card_new()`. 54762306a36Sopenharmony_ci 54862306a36Sopenharmony_ciThe first argument, the pointer of struct device, specifies the parent 54962306a36Sopenharmony_cidevice. For PCI devices, typically ``&pci->`` is passed there. 55062306a36Sopenharmony_ci 55162306a36Sopenharmony_ciComponents 55262306a36Sopenharmony_ci---------- 55362306a36Sopenharmony_ci 55462306a36Sopenharmony_ciAfter the card is created, you can attach the components (devices) to 55562306a36Sopenharmony_cithe card instance. In an ALSA driver, a component is represented as a 55662306a36Sopenharmony_cistruct snd_device object. A component 55762306a36Sopenharmony_cican be a PCM instance, a control interface, a raw MIDI interface, etc. 55862306a36Sopenharmony_ciEach such instance has one component entry. 55962306a36Sopenharmony_ci 56062306a36Sopenharmony_ciA component can be created via the :c:func:`snd_device_new()` 56162306a36Sopenharmony_cifunction:: 56262306a36Sopenharmony_ci 56362306a36Sopenharmony_ci snd_device_new(card, SNDRV_DEV_XXX, chip, &ops); 56462306a36Sopenharmony_ci 56562306a36Sopenharmony_ciThis takes the card pointer, the device-level (``SNDRV_DEV_XXX``), the 56662306a36Sopenharmony_cidata pointer, and the callback pointers (``&ops``). The device-level 56762306a36Sopenharmony_cidefines the type of components and the order of registration and 56862306a36Sopenharmony_cide-registration. For most components, the device-level is already 56962306a36Sopenharmony_cidefined. For a user-defined component, you can use 57062306a36Sopenharmony_ci``SNDRV_DEV_LOWLEVEL``. 57162306a36Sopenharmony_ci 57262306a36Sopenharmony_ciThis function itself doesn't allocate the data space. The data must be 57362306a36Sopenharmony_ciallocated manually beforehand, and its pointer is passed as the 57462306a36Sopenharmony_ciargument. This pointer (``chip`` in the above example) is used as the 57562306a36Sopenharmony_ciidentifier for the instance. 57662306a36Sopenharmony_ci 57762306a36Sopenharmony_ciEach pre-defined ALSA component such as AC97 and PCM calls 57862306a36Sopenharmony_ci:c:func:`snd_device_new()` inside its constructor. The destructor 57962306a36Sopenharmony_cifor each component is defined in the callback pointers. Hence, you don't 58062306a36Sopenharmony_cineed to take care of calling a destructor for such a component. 58162306a36Sopenharmony_ci 58262306a36Sopenharmony_ciIf you wish to create your own component, you need to set the destructor 58362306a36Sopenharmony_cifunction to the dev_free callback in the ``ops``, so that it can be 58462306a36Sopenharmony_cireleased automatically via :c:func:`snd_card_free()`. The next 58562306a36Sopenharmony_ciexample will show an implementation of chip-specific data. 58662306a36Sopenharmony_ci 58762306a36Sopenharmony_ciChip-Specific Data 58862306a36Sopenharmony_ci------------------ 58962306a36Sopenharmony_ci 59062306a36Sopenharmony_ciChip-specific information, e.g. the I/O port address, its resource 59162306a36Sopenharmony_cipointer, or the irq number, is stored in the chip-specific record:: 59262306a36Sopenharmony_ci 59362306a36Sopenharmony_ci struct mychip { 59462306a36Sopenharmony_ci .... 59562306a36Sopenharmony_ci }; 59662306a36Sopenharmony_ci 59762306a36Sopenharmony_ci 59862306a36Sopenharmony_ciIn general, there are two ways of allocating the chip record. 59962306a36Sopenharmony_ci 60062306a36Sopenharmony_ci1. Allocating via :c:func:`snd_card_new()`. 60162306a36Sopenharmony_ci~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 60262306a36Sopenharmony_ci 60362306a36Sopenharmony_ciAs mentioned above, you can pass the extra-data-length to the 5th 60462306a36Sopenharmony_ciargument of :c:func:`snd_card_new()`, e.g.:: 60562306a36Sopenharmony_ci 60662306a36Sopenharmony_ci err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, 60762306a36Sopenharmony_ci sizeof(struct mychip), &card); 60862306a36Sopenharmony_ci 60962306a36Sopenharmony_cistruct mychip is the type of the chip record. 61062306a36Sopenharmony_ci 61162306a36Sopenharmony_ciIn return, the allocated record can be accessed as 61262306a36Sopenharmony_ci 61362306a36Sopenharmony_ci:: 61462306a36Sopenharmony_ci 61562306a36Sopenharmony_ci struct mychip *chip = card->private_data; 61662306a36Sopenharmony_ci 61762306a36Sopenharmony_ciWith this method, you don't have to allocate twice. The record is 61862306a36Sopenharmony_cireleased together with the card instance. 61962306a36Sopenharmony_ci 62062306a36Sopenharmony_ci2. Allocating an extra device. 62162306a36Sopenharmony_ci~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 62262306a36Sopenharmony_ci 62362306a36Sopenharmony_ciAfter allocating a card instance via :c:func:`snd_card_new()` 62462306a36Sopenharmony_ci(with ``0`` on the 4th arg), call :c:func:`kzalloc()`:: 62562306a36Sopenharmony_ci 62662306a36Sopenharmony_ci struct snd_card *card; 62762306a36Sopenharmony_ci struct mychip *chip; 62862306a36Sopenharmony_ci err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, 62962306a36Sopenharmony_ci 0, &card); 63062306a36Sopenharmony_ci ..... 63162306a36Sopenharmony_ci chip = kzalloc(sizeof(*chip), GFP_KERNEL); 63262306a36Sopenharmony_ci 63362306a36Sopenharmony_ciThe chip record should have the field to hold the card pointer at least, 63462306a36Sopenharmony_ci 63562306a36Sopenharmony_ci:: 63662306a36Sopenharmony_ci 63762306a36Sopenharmony_ci struct mychip { 63862306a36Sopenharmony_ci struct snd_card *card; 63962306a36Sopenharmony_ci .... 64062306a36Sopenharmony_ci }; 64162306a36Sopenharmony_ci 64262306a36Sopenharmony_ci 64362306a36Sopenharmony_ciThen, set the card pointer in the returned chip instance:: 64462306a36Sopenharmony_ci 64562306a36Sopenharmony_ci chip->card = card; 64662306a36Sopenharmony_ci 64762306a36Sopenharmony_ciNext, initialize the fields, and register this chip record as a 64862306a36Sopenharmony_cilow-level device with a specified ``ops``:: 64962306a36Sopenharmony_ci 65062306a36Sopenharmony_ci static const struct snd_device_ops ops = { 65162306a36Sopenharmony_ci .dev_free = snd_mychip_dev_free, 65262306a36Sopenharmony_ci }; 65362306a36Sopenharmony_ci .... 65462306a36Sopenharmony_ci snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops); 65562306a36Sopenharmony_ci 65662306a36Sopenharmony_ci:c:func:`snd_mychip_dev_free()` is the device-destructor 65762306a36Sopenharmony_cifunction, which will call the real destructor:: 65862306a36Sopenharmony_ci 65962306a36Sopenharmony_ci static int snd_mychip_dev_free(struct snd_device *device) 66062306a36Sopenharmony_ci { 66162306a36Sopenharmony_ci return snd_mychip_free(device->device_data); 66262306a36Sopenharmony_ci } 66362306a36Sopenharmony_ci 66462306a36Sopenharmony_ciwhere :c:func:`snd_mychip_free()` is the real destructor. 66562306a36Sopenharmony_ci 66662306a36Sopenharmony_ciThe demerit of this method is the obviously larger amount of code. 66762306a36Sopenharmony_ciThe merit is, however, that you can trigger your own callback at 66862306a36Sopenharmony_ciregistering and disconnecting the card via a setting in snd_device_ops. 66962306a36Sopenharmony_ciAbout registering and disconnecting the card, see the subsections 67062306a36Sopenharmony_cibelow. 67162306a36Sopenharmony_ci 67262306a36Sopenharmony_ci 67362306a36Sopenharmony_ciRegistration and Release 67462306a36Sopenharmony_ci------------------------ 67562306a36Sopenharmony_ci 67662306a36Sopenharmony_ciAfter all components are assigned, register the card instance by calling 67762306a36Sopenharmony_ci:c:func:`snd_card_register()`. Access to the device files is 67862306a36Sopenharmony_cienabled at this point. That is, before 67962306a36Sopenharmony_ci:c:func:`snd_card_register()` is called, the components are safely 68062306a36Sopenharmony_ciinaccessible from external side. If this call fails, exit the probe 68162306a36Sopenharmony_cifunction after releasing the card via :c:func:`snd_card_free()`. 68262306a36Sopenharmony_ci 68362306a36Sopenharmony_ciFor releasing the card instance, you can call simply 68462306a36Sopenharmony_ci:c:func:`snd_card_free()`. As mentioned earlier, all components 68562306a36Sopenharmony_ciare released automatically by this call. 68662306a36Sopenharmony_ci 68762306a36Sopenharmony_ciFor a device which allows hotplugging, you can use 68862306a36Sopenharmony_ci:c:func:`snd_card_free_when_closed()`. This one will postpone 68962306a36Sopenharmony_cithe destruction until all devices are closed. 69062306a36Sopenharmony_ci 69162306a36Sopenharmony_ciPCI Resource Management 69262306a36Sopenharmony_ci======================= 69362306a36Sopenharmony_ci 69462306a36Sopenharmony_ciFull Code Example 69562306a36Sopenharmony_ci----------------- 69662306a36Sopenharmony_ci 69762306a36Sopenharmony_ciIn this section, we'll complete the chip-specific constructor, 69862306a36Sopenharmony_cidestructor and PCI entries. Example code is shown first, below:: 69962306a36Sopenharmony_ci 70062306a36Sopenharmony_ci struct mychip { 70162306a36Sopenharmony_ci struct snd_card *card; 70262306a36Sopenharmony_ci struct pci_dev *pci; 70362306a36Sopenharmony_ci 70462306a36Sopenharmony_ci unsigned long port; 70562306a36Sopenharmony_ci int irq; 70662306a36Sopenharmony_ci }; 70762306a36Sopenharmony_ci 70862306a36Sopenharmony_ci static int snd_mychip_free(struct mychip *chip) 70962306a36Sopenharmony_ci { 71062306a36Sopenharmony_ci /* disable hardware here if any */ 71162306a36Sopenharmony_ci .... /* (not implemented in this document) */ 71262306a36Sopenharmony_ci 71362306a36Sopenharmony_ci /* release the irq */ 71462306a36Sopenharmony_ci if (chip->irq >= 0) 71562306a36Sopenharmony_ci free_irq(chip->irq, chip); 71662306a36Sopenharmony_ci /* release the I/O ports & memory */ 71762306a36Sopenharmony_ci pci_release_regions(chip->pci); 71862306a36Sopenharmony_ci /* disable the PCI entry */ 71962306a36Sopenharmony_ci pci_disable_device(chip->pci); 72062306a36Sopenharmony_ci /* release the data */ 72162306a36Sopenharmony_ci kfree(chip); 72262306a36Sopenharmony_ci return 0; 72362306a36Sopenharmony_ci } 72462306a36Sopenharmony_ci 72562306a36Sopenharmony_ci /* chip-specific constructor */ 72662306a36Sopenharmony_ci static int snd_mychip_create(struct snd_card *card, 72762306a36Sopenharmony_ci struct pci_dev *pci, 72862306a36Sopenharmony_ci struct mychip **rchip) 72962306a36Sopenharmony_ci { 73062306a36Sopenharmony_ci struct mychip *chip; 73162306a36Sopenharmony_ci int err; 73262306a36Sopenharmony_ci static const struct snd_device_ops ops = { 73362306a36Sopenharmony_ci .dev_free = snd_mychip_dev_free, 73462306a36Sopenharmony_ci }; 73562306a36Sopenharmony_ci 73662306a36Sopenharmony_ci *rchip = NULL; 73762306a36Sopenharmony_ci 73862306a36Sopenharmony_ci /* initialize the PCI entry */ 73962306a36Sopenharmony_ci err = pci_enable_device(pci); 74062306a36Sopenharmony_ci if (err < 0) 74162306a36Sopenharmony_ci return err; 74262306a36Sopenharmony_ci /* check PCI availability (28bit DMA) */ 74362306a36Sopenharmony_ci if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 || 74462306a36Sopenharmony_ci pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) { 74562306a36Sopenharmony_ci printk(KERN_ERR "error to set 28bit mask DMA\n"); 74662306a36Sopenharmony_ci pci_disable_device(pci); 74762306a36Sopenharmony_ci return -ENXIO; 74862306a36Sopenharmony_ci } 74962306a36Sopenharmony_ci 75062306a36Sopenharmony_ci chip = kzalloc(sizeof(*chip), GFP_KERNEL); 75162306a36Sopenharmony_ci if (chip == NULL) { 75262306a36Sopenharmony_ci pci_disable_device(pci); 75362306a36Sopenharmony_ci return -ENOMEM; 75462306a36Sopenharmony_ci } 75562306a36Sopenharmony_ci 75662306a36Sopenharmony_ci /* initialize the stuff */ 75762306a36Sopenharmony_ci chip->card = card; 75862306a36Sopenharmony_ci chip->pci = pci; 75962306a36Sopenharmony_ci chip->irq = -1; 76062306a36Sopenharmony_ci 76162306a36Sopenharmony_ci /* (1) PCI resource allocation */ 76262306a36Sopenharmony_ci err = pci_request_regions(pci, "My Chip"); 76362306a36Sopenharmony_ci if (err < 0) { 76462306a36Sopenharmony_ci kfree(chip); 76562306a36Sopenharmony_ci pci_disable_device(pci); 76662306a36Sopenharmony_ci return err; 76762306a36Sopenharmony_ci } 76862306a36Sopenharmony_ci chip->port = pci_resource_start(pci, 0); 76962306a36Sopenharmony_ci if (request_irq(pci->irq, snd_mychip_interrupt, 77062306a36Sopenharmony_ci IRQF_SHARED, KBUILD_MODNAME, chip)) { 77162306a36Sopenharmony_ci printk(KERN_ERR "cannot grab irq %d\n", pci->irq); 77262306a36Sopenharmony_ci snd_mychip_free(chip); 77362306a36Sopenharmony_ci return -EBUSY; 77462306a36Sopenharmony_ci } 77562306a36Sopenharmony_ci chip->irq = pci->irq; 77662306a36Sopenharmony_ci card->sync_irq = chip->irq; 77762306a36Sopenharmony_ci 77862306a36Sopenharmony_ci /* (2) initialization of the chip hardware */ 77962306a36Sopenharmony_ci .... /* (not implemented in this document) */ 78062306a36Sopenharmony_ci 78162306a36Sopenharmony_ci err = snd_device_new(card, SNDRV_DEV_LOWLEVEL, chip, &ops); 78262306a36Sopenharmony_ci if (err < 0) { 78362306a36Sopenharmony_ci snd_mychip_free(chip); 78462306a36Sopenharmony_ci return err; 78562306a36Sopenharmony_ci } 78662306a36Sopenharmony_ci 78762306a36Sopenharmony_ci *rchip = chip; 78862306a36Sopenharmony_ci return 0; 78962306a36Sopenharmony_ci } 79062306a36Sopenharmony_ci 79162306a36Sopenharmony_ci /* PCI IDs */ 79262306a36Sopenharmony_ci static struct pci_device_id snd_mychip_ids[] = { 79362306a36Sopenharmony_ci { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR, 79462306a36Sopenharmony_ci PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, }, 79562306a36Sopenharmony_ci .... 79662306a36Sopenharmony_ci { 0, } 79762306a36Sopenharmony_ci }; 79862306a36Sopenharmony_ci MODULE_DEVICE_TABLE(pci, snd_mychip_ids); 79962306a36Sopenharmony_ci 80062306a36Sopenharmony_ci /* pci_driver definition */ 80162306a36Sopenharmony_ci static struct pci_driver driver = { 80262306a36Sopenharmony_ci .name = KBUILD_MODNAME, 80362306a36Sopenharmony_ci .id_table = snd_mychip_ids, 80462306a36Sopenharmony_ci .probe = snd_mychip_probe, 80562306a36Sopenharmony_ci .remove = snd_mychip_remove, 80662306a36Sopenharmony_ci }; 80762306a36Sopenharmony_ci 80862306a36Sopenharmony_ci /* module initialization */ 80962306a36Sopenharmony_ci static int __init alsa_card_mychip_init(void) 81062306a36Sopenharmony_ci { 81162306a36Sopenharmony_ci return pci_register_driver(&driver); 81262306a36Sopenharmony_ci } 81362306a36Sopenharmony_ci 81462306a36Sopenharmony_ci /* module clean up */ 81562306a36Sopenharmony_ci static void __exit alsa_card_mychip_exit(void) 81662306a36Sopenharmony_ci { 81762306a36Sopenharmony_ci pci_unregister_driver(&driver); 81862306a36Sopenharmony_ci } 81962306a36Sopenharmony_ci 82062306a36Sopenharmony_ci module_init(alsa_card_mychip_init) 82162306a36Sopenharmony_ci module_exit(alsa_card_mychip_exit) 82262306a36Sopenharmony_ci 82362306a36Sopenharmony_ci EXPORT_NO_SYMBOLS; /* for old kernels only */ 82462306a36Sopenharmony_ci 82562306a36Sopenharmony_ciSome Hafta's 82662306a36Sopenharmony_ci------------ 82762306a36Sopenharmony_ci 82862306a36Sopenharmony_ciThe allocation of PCI resources is done in the ``probe`` function, and 82962306a36Sopenharmony_ciusually an extra :c:func:`xxx_create()` function is written for this 83062306a36Sopenharmony_cipurpose. 83162306a36Sopenharmony_ci 83262306a36Sopenharmony_ciIn the case of PCI devices, you first have to call the 83362306a36Sopenharmony_ci:c:func:`pci_enable_device()` function before allocating 83462306a36Sopenharmony_ciresources. Also, you need to set the proper PCI DMA mask to limit the 83562306a36Sopenharmony_ciaccessed I/O range. In some cases, you might need to call 83662306a36Sopenharmony_ci:c:func:`pci_set_master()` function, too. 83762306a36Sopenharmony_ci 83862306a36Sopenharmony_ciSuppose a 28bit mask, the code to be added would look like:: 83962306a36Sopenharmony_ci 84062306a36Sopenharmony_ci err = pci_enable_device(pci); 84162306a36Sopenharmony_ci if (err < 0) 84262306a36Sopenharmony_ci return err; 84362306a36Sopenharmony_ci if (pci_set_dma_mask(pci, DMA_BIT_MASK(28)) < 0 || 84462306a36Sopenharmony_ci pci_set_consistent_dma_mask(pci, DMA_BIT_MASK(28)) < 0) { 84562306a36Sopenharmony_ci printk(KERN_ERR "error to set 28bit mask DMA\n"); 84662306a36Sopenharmony_ci pci_disable_device(pci); 84762306a36Sopenharmony_ci return -ENXIO; 84862306a36Sopenharmony_ci } 84962306a36Sopenharmony_ci 85062306a36Sopenharmony_ci 85162306a36Sopenharmony_ciResource Allocation 85262306a36Sopenharmony_ci------------------- 85362306a36Sopenharmony_ci 85462306a36Sopenharmony_ciThe allocation of I/O ports and irqs is done via standard kernel 85562306a36Sopenharmony_cifunctions. These resources must be released in the destructor 85662306a36Sopenharmony_cifunction (see below). 85762306a36Sopenharmony_ci 85862306a36Sopenharmony_ciNow assume that the PCI device has an I/O port with 8 bytes and an 85962306a36Sopenharmony_ciinterrupt. Then struct mychip will have the 86062306a36Sopenharmony_cifollowing fields:: 86162306a36Sopenharmony_ci 86262306a36Sopenharmony_ci struct mychip { 86362306a36Sopenharmony_ci struct snd_card *card; 86462306a36Sopenharmony_ci 86562306a36Sopenharmony_ci unsigned long port; 86662306a36Sopenharmony_ci int irq; 86762306a36Sopenharmony_ci }; 86862306a36Sopenharmony_ci 86962306a36Sopenharmony_ci 87062306a36Sopenharmony_ciFor an I/O port (and also a memory region), you need to have the 87162306a36Sopenharmony_ciresource pointer for the standard resource management. For an irq, you 87262306a36Sopenharmony_cihave to keep only the irq number (integer). But you need to initialize 87362306a36Sopenharmony_cithis number to -1 before actual allocation, since irq 0 is valid. The 87462306a36Sopenharmony_ciport address and its resource pointer can be initialized as null by 87562306a36Sopenharmony_ci:c:func:`kzalloc()` automatically, so you don't have to take care of 87662306a36Sopenharmony_ciresetting them. 87762306a36Sopenharmony_ci 87862306a36Sopenharmony_ciThe allocation of an I/O port is done like this:: 87962306a36Sopenharmony_ci 88062306a36Sopenharmony_ci err = pci_request_regions(pci, "My Chip"); 88162306a36Sopenharmony_ci if (err < 0) { 88262306a36Sopenharmony_ci kfree(chip); 88362306a36Sopenharmony_ci pci_disable_device(pci); 88462306a36Sopenharmony_ci return err; 88562306a36Sopenharmony_ci } 88662306a36Sopenharmony_ci chip->port = pci_resource_start(pci, 0); 88762306a36Sopenharmony_ci 88862306a36Sopenharmony_ciIt will reserve the I/O port region of 8 bytes of the given PCI device. 88962306a36Sopenharmony_ciThe returned value, ``chip->res_port``, is allocated via 89062306a36Sopenharmony_ci:c:func:`kmalloc()` by :c:func:`request_region()`. The pointer 89162306a36Sopenharmony_cimust be released via :c:func:`kfree()`, but there is a problem with 89262306a36Sopenharmony_cithis. This issue will be explained later. 89362306a36Sopenharmony_ci 89462306a36Sopenharmony_ciThe allocation of an interrupt source is done like this:: 89562306a36Sopenharmony_ci 89662306a36Sopenharmony_ci if (request_irq(pci->irq, snd_mychip_interrupt, 89762306a36Sopenharmony_ci IRQF_SHARED, KBUILD_MODNAME, chip)) { 89862306a36Sopenharmony_ci printk(KERN_ERR "cannot grab irq %d\n", pci->irq); 89962306a36Sopenharmony_ci snd_mychip_free(chip); 90062306a36Sopenharmony_ci return -EBUSY; 90162306a36Sopenharmony_ci } 90262306a36Sopenharmony_ci chip->irq = pci->irq; 90362306a36Sopenharmony_ci 90462306a36Sopenharmony_ciwhere :c:func:`snd_mychip_interrupt()` is the interrupt handler 90562306a36Sopenharmony_cidefined `later <PCM Interrupt Handler_>`__. Note that 90662306a36Sopenharmony_ci``chip->irq`` should be defined only when :c:func:`request_irq()` 90762306a36Sopenharmony_cisucceeded. 90862306a36Sopenharmony_ci 90962306a36Sopenharmony_ciOn the PCI bus, interrupts can be shared. Thus, ``IRQF_SHARED`` is used 91062306a36Sopenharmony_cias the interrupt flag of :c:func:`request_irq()`. 91162306a36Sopenharmony_ci 91262306a36Sopenharmony_ciThe last argument of :c:func:`request_irq()` is the data pointer 91362306a36Sopenharmony_cipassed to the interrupt handler. Usually, the chip-specific record is 91462306a36Sopenharmony_ciused for that, but you can use what you like, too. 91562306a36Sopenharmony_ci 91662306a36Sopenharmony_ciI won't give details about the interrupt handler at this point, but at 91762306a36Sopenharmony_cileast its appearance can be explained now. The interrupt handler looks 91862306a36Sopenharmony_ciusually as follows:: 91962306a36Sopenharmony_ci 92062306a36Sopenharmony_ci static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id) 92162306a36Sopenharmony_ci { 92262306a36Sopenharmony_ci struct mychip *chip = dev_id; 92362306a36Sopenharmony_ci .... 92462306a36Sopenharmony_ci return IRQ_HANDLED; 92562306a36Sopenharmony_ci } 92662306a36Sopenharmony_ci 92762306a36Sopenharmony_ciAfter requesting the IRQ, you can passed it to ``card->sync_irq`` 92862306a36Sopenharmony_cifield:: 92962306a36Sopenharmony_ci 93062306a36Sopenharmony_ci card->irq = chip->irq; 93162306a36Sopenharmony_ci 93262306a36Sopenharmony_ciThis allows the PCM core to automatically call 93362306a36Sopenharmony_ci:c:func:`synchronize_irq()` at the right time, like before ``hw_free``. 93462306a36Sopenharmony_ciSee the later section `sync_stop callback`_ for details. 93562306a36Sopenharmony_ci 93662306a36Sopenharmony_ciNow let's write the corresponding destructor for the resources above. 93762306a36Sopenharmony_ciThe role of destructor is simple: disable the hardware (if already 93862306a36Sopenharmony_ciactivated) and release the resources. So far, we have no hardware part, 93962306a36Sopenharmony_ciso the disabling code is not written here. 94062306a36Sopenharmony_ci 94162306a36Sopenharmony_ciTo release the resources, the “check-and-release” method is a safer way. 94262306a36Sopenharmony_ciFor the interrupt, do like this:: 94362306a36Sopenharmony_ci 94462306a36Sopenharmony_ci if (chip->irq >= 0) 94562306a36Sopenharmony_ci free_irq(chip->irq, chip); 94662306a36Sopenharmony_ci 94762306a36Sopenharmony_ciSince the irq number can start from 0, you should initialize 94862306a36Sopenharmony_ci``chip->irq`` with a negative value (e.g. -1), so that you can check 94962306a36Sopenharmony_cithe validity of the irq number as above. 95062306a36Sopenharmony_ci 95162306a36Sopenharmony_ciWhen you requested I/O ports or memory regions via 95262306a36Sopenharmony_ci:c:func:`pci_request_region()` or 95362306a36Sopenharmony_ci:c:func:`pci_request_regions()` like in this example, release the 95462306a36Sopenharmony_ciresource(s) using the corresponding function, 95562306a36Sopenharmony_ci:c:func:`pci_release_region()` or 95662306a36Sopenharmony_ci:c:func:`pci_release_regions()`:: 95762306a36Sopenharmony_ci 95862306a36Sopenharmony_ci pci_release_regions(chip->pci); 95962306a36Sopenharmony_ci 96062306a36Sopenharmony_ciWhen you requested manually via :c:func:`request_region()` or 96162306a36Sopenharmony_ci:c:func:`request_mem_region()`, you can release it via 96262306a36Sopenharmony_ci:c:func:`release_resource()`. Suppose that you keep the resource 96362306a36Sopenharmony_cipointer returned from :c:func:`request_region()` in 96462306a36Sopenharmony_cichip->res_port, the release procedure looks like:: 96562306a36Sopenharmony_ci 96662306a36Sopenharmony_ci release_and_free_resource(chip->res_port); 96762306a36Sopenharmony_ci 96862306a36Sopenharmony_ciDon't forget to call :c:func:`pci_disable_device()` before the 96962306a36Sopenharmony_ciend. 97062306a36Sopenharmony_ci 97162306a36Sopenharmony_ciAnd finally, release the chip-specific record:: 97262306a36Sopenharmony_ci 97362306a36Sopenharmony_ci kfree(chip); 97462306a36Sopenharmony_ci 97562306a36Sopenharmony_ciWe didn't implement the hardware disabling part above. If you 97662306a36Sopenharmony_cineed to do this, please note that the destructor may be called even 97762306a36Sopenharmony_cibefore the initialization of the chip is completed. It would be better 97862306a36Sopenharmony_cito have a flag to skip hardware disabling if the hardware was not 97962306a36Sopenharmony_ciinitialized yet. 98062306a36Sopenharmony_ci 98162306a36Sopenharmony_ciWhen the chip-data is assigned to the card using 98262306a36Sopenharmony_ci:c:func:`snd_device_new()` with ``SNDRV_DEV_LOWLELVEL``, its 98362306a36Sopenharmony_cidestructor is called last. That is, it is assured that all other 98462306a36Sopenharmony_cicomponents like PCMs and controls have already been released. You don't 98562306a36Sopenharmony_cihave to stop PCMs, etc. explicitly, but just call low-level hardware 98662306a36Sopenharmony_cistopping. 98762306a36Sopenharmony_ci 98862306a36Sopenharmony_ciThe management of a memory-mapped region is almost as same as the 98962306a36Sopenharmony_cimanagement of an I/O port. You'll need two fields as follows:: 99062306a36Sopenharmony_ci 99162306a36Sopenharmony_ci struct mychip { 99262306a36Sopenharmony_ci .... 99362306a36Sopenharmony_ci unsigned long iobase_phys; 99462306a36Sopenharmony_ci void __iomem *iobase_virt; 99562306a36Sopenharmony_ci }; 99662306a36Sopenharmony_ci 99762306a36Sopenharmony_ciand the allocation would look like below:: 99862306a36Sopenharmony_ci 99962306a36Sopenharmony_ci err = pci_request_regions(pci, "My Chip"); 100062306a36Sopenharmony_ci if (err < 0) { 100162306a36Sopenharmony_ci kfree(chip); 100262306a36Sopenharmony_ci return err; 100362306a36Sopenharmony_ci } 100462306a36Sopenharmony_ci chip->iobase_phys = pci_resource_start(pci, 0); 100562306a36Sopenharmony_ci chip->iobase_virt = ioremap(chip->iobase_phys, 100662306a36Sopenharmony_ci pci_resource_len(pci, 0)); 100762306a36Sopenharmony_ci 100862306a36Sopenharmony_ciand the corresponding destructor would be:: 100962306a36Sopenharmony_ci 101062306a36Sopenharmony_ci static int snd_mychip_free(struct mychip *chip) 101162306a36Sopenharmony_ci { 101262306a36Sopenharmony_ci .... 101362306a36Sopenharmony_ci if (chip->iobase_virt) 101462306a36Sopenharmony_ci iounmap(chip->iobase_virt); 101562306a36Sopenharmony_ci .... 101662306a36Sopenharmony_ci pci_release_regions(chip->pci); 101762306a36Sopenharmony_ci .... 101862306a36Sopenharmony_ci } 101962306a36Sopenharmony_ci 102062306a36Sopenharmony_ciOf course, a modern way with :c:func:`pci_iomap()` will make things a 102162306a36Sopenharmony_cibit easier, too:: 102262306a36Sopenharmony_ci 102362306a36Sopenharmony_ci err = pci_request_regions(pci, "My Chip"); 102462306a36Sopenharmony_ci if (err < 0) { 102562306a36Sopenharmony_ci kfree(chip); 102662306a36Sopenharmony_ci return err; 102762306a36Sopenharmony_ci } 102862306a36Sopenharmony_ci chip->iobase_virt = pci_iomap(pci, 0, 0); 102962306a36Sopenharmony_ci 103062306a36Sopenharmony_ciwhich is paired with :c:func:`pci_iounmap()` at destructor. 103162306a36Sopenharmony_ci 103262306a36Sopenharmony_ci 103362306a36Sopenharmony_ciPCI Entries 103462306a36Sopenharmony_ci----------- 103562306a36Sopenharmony_ci 103662306a36Sopenharmony_ciSo far, so good. Let's finish the missing PCI stuff. At first, we need a 103762306a36Sopenharmony_cistruct pci_device_id table for 103862306a36Sopenharmony_cithis chipset. It's a table of PCI vendor/device ID number, and some 103962306a36Sopenharmony_cimasks. 104062306a36Sopenharmony_ci 104162306a36Sopenharmony_ciFor example:: 104262306a36Sopenharmony_ci 104362306a36Sopenharmony_ci static struct pci_device_id snd_mychip_ids[] = { 104462306a36Sopenharmony_ci { PCI_VENDOR_ID_FOO, PCI_DEVICE_ID_BAR, 104562306a36Sopenharmony_ci PCI_ANY_ID, PCI_ANY_ID, 0, 0, 0, }, 104662306a36Sopenharmony_ci .... 104762306a36Sopenharmony_ci { 0, } 104862306a36Sopenharmony_ci }; 104962306a36Sopenharmony_ci MODULE_DEVICE_TABLE(pci, snd_mychip_ids); 105062306a36Sopenharmony_ci 105162306a36Sopenharmony_ciThe first and second fields of the struct pci_device_id are the vendor 105262306a36Sopenharmony_ciand device IDs. If you have no reason to filter the matching devices, you can 105362306a36Sopenharmony_cileave the remaining fields as above. The last field of the 105462306a36Sopenharmony_cistruct pci_device_id contains private data for this entry. You can specify 105562306a36Sopenharmony_ciany value here, for example, to define specific operations for supported 105662306a36Sopenharmony_cidevice IDs. Such an example is found in the intel8x0 driver. 105762306a36Sopenharmony_ci 105862306a36Sopenharmony_ciThe last entry of this list is the terminator. You must specify this 105962306a36Sopenharmony_ciall-zero entry. 106062306a36Sopenharmony_ci 106162306a36Sopenharmony_ciThen, prepare the struct pci_driver 106262306a36Sopenharmony_cirecord:: 106362306a36Sopenharmony_ci 106462306a36Sopenharmony_ci static struct pci_driver driver = { 106562306a36Sopenharmony_ci .name = KBUILD_MODNAME, 106662306a36Sopenharmony_ci .id_table = snd_mychip_ids, 106762306a36Sopenharmony_ci .probe = snd_mychip_probe, 106862306a36Sopenharmony_ci .remove = snd_mychip_remove, 106962306a36Sopenharmony_ci }; 107062306a36Sopenharmony_ci 107162306a36Sopenharmony_ciThe ``probe`` and ``remove`` functions have already been defined in 107262306a36Sopenharmony_cithe previous sections. The ``name`` field is the name string of this 107362306a36Sopenharmony_cidevice. Note that you must not use slashes (“/”) in this string. 107462306a36Sopenharmony_ci 107562306a36Sopenharmony_ciAnd at last, the module entries:: 107662306a36Sopenharmony_ci 107762306a36Sopenharmony_ci static int __init alsa_card_mychip_init(void) 107862306a36Sopenharmony_ci { 107962306a36Sopenharmony_ci return pci_register_driver(&driver); 108062306a36Sopenharmony_ci } 108162306a36Sopenharmony_ci 108262306a36Sopenharmony_ci static void __exit alsa_card_mychip_exit(void) 108362306a36Sopenharmony_ci { 108462306a36Sopenharmony_ci pci_unregister_driver(&driver); 108562306a36Sopenharmony_ci } 108662306a36Sopenharmony_ci 108762306a36Sopenharmony_ci module_init(alsa_card_mychip_init) 108862306a36Sopenharmony_ci module_exit(alsa_card_mychip_exit) 108962306a36Sopenharmony_ci 109062306a36Sopenharmony_ciNote that these module entries are tagged with ``__init`` and ``__exit`` 109162306a36Sopenharmony_ciprefixes. 109262306a36Sopenharmony_ci 109362306a36Sopenharmony_ciThat's all! 109462306a36Sopenharmony_ci 109562306a36Sopenharmony_ciPCM Interface 109662306a36Sopenharmony_ci============= 109762306a36Sopenharmony_ci 109862306a36Sopenharmony_ciGeneral 109962306a36Sopenharmony_ci------- 110062306a36Sopenharmony_ci 110162306a36Sopenharmony_ciThe PCM middle layer of ALSA is quite powerful and it is only necessary 110262306a36Sopenharmony_cifor each driver to implement the low-level functions to access its 110362306a36Sopenharmony_cihardware. 110462306a36Sopenharmony_ci 110562306a36Sopenharmony_ciTo access the PCM layer, you need to include ``<sound/pcm.h>`` 110662306a36Sopenharmony_cifirst. In addition, ``<sound/pcm_params.h>`` might be needed if you 110762306a36Sopenharmony_ciaccess some functions related with hw_param. 110862306a36Sopenharmony_ci 110962306a36Sopenharmony_ciEach card device can have up to four PCM instances. A PCM instance 111062306a36Sopenharmony_cicorresponds to a PCM device file. The limitation of number of instances 111162306a36Sopenharmony_cicomes only from the available bit size of Linux' device numbers. 111262306a36Sopenharmony_ciOnce 64bit device numbers are used, we'll have more PCM instances 111362306a36Sopenharmony_ciavailable. 111462306a36Sopenharmony_ci 111562306a36Sopenharmony_ciA PCM instance consists of PCM playback and capture streams, and each 111662306a36Sopenharmony_ciPCM stream consists of one or more PCM substreams. Some soundcards 111762306a36Sopenharmony_cisupport multiple playback functions. For example, emu10k1 has a PCM 111862306a36Sopenharmony_ciplayback of 32 stereo substreams. In this case, at each open, a free 111962306a36Sopenharmony_cisubstream is (usually) automatically chosen and opened. Meanwhile, when 112062306a36Sopenharmony_cionly one substream exists and it was already opened, a subsequent open 112162306a36Sopenharmony_ciwill either block or error with ``EAGAIN`` according to the file open 112262306a36Sopenharmony_cimode. But you don't have to care about such details in your driver. The 112362306a36Sopenharmony_ciPCM middle layer will take care of such work. 112462306a36Sopenharmony_ci 112562306a36Sopenharmony_ciFull Code Example 112662306a36Sopenharmony_ci----------------- 112762306a36Sopenharmony_ci 112862306a36Sopenharmony_ciThe example code below does not include any hardware access routines but 112962306a36Sopenharmony_cishows only the skeleton, how to build up the PCM interfaces:: 113062306a36Sopenharmony_ci 113162306a36Sopenharmony_ci #include <sound/pcm.h> 113262306a36Sopenharmony_ci .... 113362306a36Sopenharmony_ci 113462306a36Sopenharmony_ci /* hardware definition */ 113562306a36Sopenharmony_ci static struct snd_pcm_hardware snd_mychip_playback_hw = { 113662306a36Sopenharmony_ci .info = (SNDRV_PCM_INFO_MMAP | 113762306a36Sopenharmony_ci SNDRV_PCM_INFO_INTERLEAVED | 113862306a36Sopenharmony_ci SNDRV_PCM_INFO_BLOCK_TRANSFER | 113962306a36Sopenharmony_ci SNDRV_PCM_INFO_MMAP_VALID), 114062306a36Sopenharmony_ci .formats = SNDRV_PCM_FMTBIT_S16_LE, 114162306a36Sopenharmony_ci .rates = SNDRV_PCM_RATE_8000_48000, 114262306a36Sopenharmony_ci .rate_min = 8000, 114362306a36Sopenharmony_ci .rate_max = 48000, 114462306a36Sopenharmony_ci .channels_min = 2, 114562306a36Sopenharmony_ci .channels_max = 2, 114662306a36Sopenharmony_ci .buffer_bytes_max = 32768, 114762306a36Sopenharmony_ci .period_bytes_min = 4096, 114862306a36Sopenharmony_ci .period_bytes_max = 32768, 114962306a36Sopenharmony_ci .periods_min = 1, 115062306a36Sopenharmony_ci .periods_max = 1024, 115162306a36Sopenharmony_ci }; 115262306a36Sopenharmony_ci 115362306a36Sopenharmony_ci /* hardware definition */ 115462306a36Sopenharmony_ci static struct snd_pcm_hardware snd_mychip_capture_hw = { 115562306a36Sopenharmony_ci .info = (SNDRV_PCM_INFO_MMAP | 115662306a36Sopenharmony_ci SNDRV_PCM_INFO_INTERLEAVED | 115762306a36Sopenharmony_ci SNDRV_PCM_INFO_BLOCK_TRANSFER | 115862306a36Sopenharmony_ci SNDRV_PCM_INFO_MMAP_VALID), 115962306a36Sopenharmony_ci .formats = SNDRV_PCM_FMTBIT_S16_LE, 116062306a36Sopenharmony_ci .rates = SNDRV_PCM_RATE_8000_48000, 116162306a36Sopenharmony_ci .rate_min = 8000, 116262306a36Sopenharmony_ci .rate_max = 48000, 116362306a36Sopenharmony_ci .channels_min = 2, 116462306a36Sopenharmony_ci .channels_max = 2, 116562306a36Sopenharmony_ci .buffer_bytes_max = 32768, 116662306a36Sopenharmony_ci .period_bytes_min = 4096, 116762306a36Sopenharmony_ci .period_bytes_max = 32768, 116862306a36Sopenharmony_ci .periods_min = 1, 116962306a36Sopenharmony_ci .periods_max = 1024, 117062306a36Sopenharmony_ci }; 117162306a36Sopenharmony_ci 117262306a36Sopenharmony_ci /* open callback */ 117362306a36Sopenharmony_ci static int snd_mychip_playback_open(struct snd_pcm_substream *substream) 117462306a36Sopenharmony_ci { 117562306a36Sopenharmony_ci struct mychip *chip = snd_pcm_substream_chip(substream); 117662306a36Sopenharmony_ci struct snd_pcm_runtime *runtime = substream->runtime; 117762306a36Sopenharmony_ci 117862306a36Sopenharmony_ci runtime->hw = snd_mychip_playback_hw; 117962306a36Sopenharmony_ci /* more hardware-initialization will be done here */ 118062306a36Sopenharmony_ci .... 118162306a36Sopenharmony_ci return 0; 118262306a36Sopenharmony_ci } 118362306a36Sopenharmony_ci 118462306a36Sopenharmony_ci /* close callback */ 118562306a36Sopenharmony_ci static int snd_mychip_playback_close(struct snd_pcm_substream *substream) 118662306a36Sopenharmony_ci { 118762306a36Sopenharmony_ci struct mychip *chip = snd_pcm_substream_chip(substream); 118862306a36Sopenharmony_ci /* the hardware-specific codes will be here */ 118962306a36Sopenharmony_ci .... 119062306a36Sopenharmony_ci return 0; 119162306a36Sopenharmony_ci 119262306a36Sopenharmony_ci } 119362306a36Sopenharmony_ci 119462306a36Sopenharmony_ci /* open callback */ 119562306a36Sopenharmony_ci static int snd_mychip_capture_open(struct snd_pcm_substream *substream) 119662306a36Sopenharmony_ci { 119762306a36Sopenharmony_ci struct mychip *chip = snd_pcm_substream_chip(substream); 119862306a36Sopenharmony_ci struct snd_pcm_runtime *runtime = substream->runtime; 119962306a36Sopenharmony_ci 120062306a36Sopenharmony_ci runtime->hw = snd_mychip_capture_hw; 120162306a36Sopenharmony_ci /* more hardware-initialization will be done here */ 120262306a36Sopenharmony_ci .... 120362306a36Sopenharmony_ci return 0; 120462306a36Sopenharmony_ci } 120562306a36Sopenharmony_ci 120662306a36Sopenharmony_ci /* close callback */ 120762306a36Sopenharmony_ci static int snd_mychip_capture_close(struct snd_pcm_substream *substream) 120862306a36Sopenharmony_ci { 120962306a36Sopenharmony_ci struct mychip *chip = snd_pcm_substream_chip(substream); 121062306a36Sopenharmony_ci /* the hardware-specific codes will be here */ 121162306a36Sopenharmony_ci .... 121262306a36Sopenharmony_ci return 0; 121362306a36Sopenharmony_ci } 121462306a36Sopenharmony_ci 121562306a36Sopenharmony_ci /* hw_params callback */ 121662306a36Sopenharmony_ci static int snd_mychip_pcm_hw_params(struct snd_pcm_substream *substream, 121762306a36Sopenharmony_ci struct snd_pcm_hw_params *hw_params) 121862306a36Sopenharmony_ci { 121962306a36Sopenharmony_ci /* the hardware-specific codes will be here */ 122062306a36Sopenharmony_ci .... 122162306a36Sopenharmony_ci return 0; 122262306a36Sopenharmony_ci } 122362306a36Sopenharmony_ci 122462306a36Sopenharmony_ci /* hw_free callback */ 122562306a36Sopenharmony_ci static int snd_mychip_pcm_hw_free(struct snd_pcm_substream *substream) 122662306a36Sopenharmony_ci { 122762306a36Sopenharmony_ci /* the hardware-specific codes will be here */ 122862306a36Sopenharmony_ci .... 122962306a36Sopenharmony_ci return 0; 123062306a36Sopenharmony_ci } 123162306a36Sopenharmony_ci 123262306a36Sopenharmony_ci /* prepare callback */ 123362306a36Sopenharmony_ci static int snd_mychip_pcm_prepare(struct snd_pcm_substream *substream) 123462306a36Sopenharmony_ci { 123562306a36Sopenharmony_ci struct mychip *chip = snd_pcm_substream_chip(substream); 123662306a36Sopenharmony_ci struct snd_pcm_runtime *runtime = substream->runtime; 123762306a36Sopenharmony_ci 123862306a36Sopenharmony_ci /* set up the hardware with the current configuration 123962306a36Sopenharmony_ci * for example... 124062306a36Sopenharmony_ci */ 124162306a36Sopenharmony_ci mychip_set_sample_format(chip, runtime->format); 124262306a36Sopenharmony_ci mychip_set_sample_rate(chip, runtime->rate); 124362306a36Sopenharmony_ci mychip_set_channels(chip, runtime->channels); 124462306a36Sopenharmony_ci mychip_set_dma_setup(chip, runtime->dma_addr, 124562306a36Sopenharmony_ci chip->buffer_size, 124662306a36Sopenharmony_ci chip->period_size); 124762306a36Sopenharmony_ci return 0; 124862306a36Sopenharmony_ci } 124962306a36Sopenharmony_ci 125062306a36Sopenharmony_ci /* trigger callback */ 125162306a36Sopenharmony_ci static int snd_mychip_pcm_trigger(struct snd_pcm_substream *substream, 125262306a36Sopenharmony_ci int cmd) 125362306a36Sopenharmony_ci { 125462306a36Sopenharmony_ci switch (cmd) { 125562306a36Sopenharmony_ci case SNDRV_PCM_TRIGGER_START: 125662306a36Sopenharmony_ci /* do something to start the PCM engine */ 125762306a36Sopenharmony_ci .... 125862306a36Sopenharmony_ci break; 125962306a36Sopenharmony_ci case SNDRV_PCM_TRIGGER_STOP: 126062306a36Sopenharmony_ci /* do something to stop the PCM engine */ 126162306a36Sopenharmony_ci .... 126262306a36Sopenharmony_ci break; 126362306a36Sopenharmony_ci default: 126462306a36Sopenharmony_ci return -EINVAL; 126562306a36Sopenharmony_ci } 126662306a36Sopenharmony_ci } 126762306a36Sopenharmony_ci 126862306a36Sopenharmony_ci /* pointer callback */ 126962306a36Sopenharmony_ci static snd_pcm_uframes_t 127062306a36Sopenharmony_ci snd_mychip_pcm_pointer(struct snd_pcm_substream *substream) 127162306a36Sopenharmony_ci { 127262306a36Sopenharmony_ci struct mychip *chip = snd_pcm_substream_chip(substream); 127362306a36Sopenharmony_ci unsigned int current_ptr; 127462306a36Sopenharmony_ci 127562306a36Sopenharmony_ci /* get the current hardware pointer */ 127662306a36Sopenharmony_ci current_ptr = mychip_get_hw_pointer(chip); 127762306a36Sopenharmony_ci return current_ptr; 127862306a36Sopenharmony_ci } 127962306a36Sopenharmony_ci 128062306a36Sopenharmony_ci /* operators */ 128162306a36Sopenharmony_ci static struct snd_pcm_ops snd_mychip_playback_ops = { 128262306a36Sopenharmony_ci .open = snd_mychip_playback_open, 128362306a36Sopenharmony_ci .close = snd_mychip_playback_close, 128462306a36Sopenharmony_ci .hw_params = snd_mychip_pcm_hw_params, 128562306a36Sopenharmony_ci .hw_free = snd_mychip_pcm_hw_free, 128662306a36Sopenharmony_ci .prepare = snd_mychip_pcm_prepare, 128762306a36Sopenharmony_ci .trigger = snd_mychip_pcm_trigger, 128862306a36Sopenharmony_ci .pointer = snd_mychip_pcm_pointer, 128962306a36Sopenharmony_ci }; 129062306a36Sopenharmony_ci 129162306a36Sopenharmony_ci /* operators */ 129262306a36Sopenharmony_ci static struct snd_pcm_ops snd_mychip_capture_ops = { 129362306a36Sopenharmony_ci .open = snd_mychip_capture_open, 129462306a36Sopenharmony_ci .close = snd_mychip_capture_close, 129562306a36Sopenharmony_ci .hw_params = snd_mychip_pcm_hw_params, 129662306a36Sopenharmony_ci .hw_free = snd_mychip_pcm_hw_free, 129762306a36Sopenharmony_ci .prepare = snd_mychip_pcm_prepare, 129862306a36Sopenharmony_ci .trigger = snd_mychip_pcm_trigger, 129962306a36Sopenharmony_ci .pointer = snd_mychip_pcm_pointer, 130062306a36Sopenharmony_ci }; 130162306a36Sopenharmony_ci 130262306a36Sopenharmony_ci /* 130362306a36Sopenharmony_ci * definitions of capture are omitted here... 130462306a36Sopenharmony_ci */ 130562306a36Sopenharmony_ci 130662306a36Sopenharmony_ci /* create a pcm device */ 130762306a36Sopenharmony_ci static int snd_mychip_new_pcm(struct mychip *chip) 130862306a36Sopenharmony_ci { 130962306a36Sopenharmony_ci struct snd_pcm *pcm; 131062306a36Sopenharmony_ci int err; 131162306a36Sopenharmony_ci 131262306a36Sopenharmony_ci err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm); 131362306a36Sopenharmony_ci if (err < 0) 131462306a36Sopenharmony_ci return err; 131562306a36Sopenharmony_ci pcm->private_data = chip; 131662306a36Sopenharmony_ci strcpy(pcm->name, "My Chip"); 131762306a36Sopenharmony_ci chip->pcm = pcm; 131862306a36Sopenharmony_ci /* set operators */ 131962306a36Sopenharmony_ci snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK, 132062306a36Sopenharmony_ci &snd_mychip_playback_ops); 132162306a36Sopenharmony_ci snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE, 132262306a36Sopenharmony_ci &snd_mychip_capture_ops); 132362306a36Sopenharmony_ci /* pre-allocation of buffers */ 132462306a36Sopenharmony_ci /* NOTE: this may fail */ 132562306a36Sopenharmony_ci snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV, 132662306a36Sopenharmony_ci &chip->pci->dev, 132762306a36Sopenharmony_ci 64*1024, 64*1024); 132862306a36Sopenharmony_ci return 0; 132962306a36Sopenharmony_ci } 133062306a36Sopenharmony_ci 133162306a36Sopenharmony_ci 133262306a36Sopenharmony_ciPCM Constructor 133362306a36Sopenharmony_ci--------------- 133462306a36Sopenharmony_ci 133562306a36Sopenharmony_ciA PCM instance is allocated by the :c:func:`snd_pcm_new()` 133662306a36Sopenharmony_cifunction. It would be better to create a constructor for the PCM, namely:: 133762306a36Sopenharmony_ci 133862306a36Sopenharmony_ci static int snd_mychip_new_pcm(struct mychip *chip) 133962306a36Sopenharmony_ci { 134062306a36Sopenharmony_ci struct snd_pcm *pcm; 134162306a36Sopenharmony_ci int err; 134262306a36Sopenharmony_ci 134362306a36Sopenharmony_ci err = snd_pcm_new(chip->card, "My Chip", 0, 1, 1, &pcm); 134462306a36Sopenharmony_ci if (err < 0) 134562306a36Sopenharmony_ci return err; 134662306a36Sopenharmony_ci pcm->private_data = chip; 134762306a36Sopenharmony_ci strcpy(pcm->name, "My Chip"); 134862306a36Sopenharmony_ci chip->pcm = pcm; 134962306a36Sopenharmony_ci ... 135062306a36Sopenharmony_ci return 0; 135162306a36Sopenharmony_ci } 135262306a36Sopenharmony_ci 135362306a36Sopenharmony_ciThe :c:func:`snd_pcm_new()` function takes six arguments. The 135462306a36Sopenharmony_cifirst argument is the card pointer to which this PCM is assigned, and 135562306a36Sopenharmony_cithe second is the ID string. 135662306a36Sopenharmony_ci 135762306a36Sopenharmony_ciThe third argument (``index``, 0 in the above) is the index of this new 135862306a36Sopenharmony_ciPCM. It begins from zero. If you create more than one PCM instances, 135962306a36Sopenharmony_cispecify the different numbers in this argument. For example, ``index = 136062306a36Sopenharmony_ci1`` for the second PCM device. 136162306a36Sopenharmony_ci 136262306a36Sopenharmony_ciThe fourth and fifth arguments are the number of substreams for playback 136362306a36Sopenharmony_ciand capture, respectively. Here 1 is used for both arguments. When no 136462306a36Sopenharmony_ciplayback or capture substreams are available, pass 0 to the 136562306a36Sopenharmony_cicorresponding argument. 136662306a36Sopenharmony_ci 136762306a36Sopenharmony_ciIf a chip supports multiple playbacks or captures, you can specify more 136862306a36Sopenharmony_cinumbers, but they must be handled properly in open/close, etc. 136962306a36Sopenharmony_cicallbacks. When you need to know which substream you are referring to, 137062306a36Sopenharmony_cithen it can be obtained from struct snd_pcm_substream data passed to each 137162306a36Sopenharmony_cicallback as follows:: 137262306a36Sopenharmony_ci 137362306a36Sopenharmony_ci struct snd_pcm_substream *substream; 137462306a36Sopenharmony_ci int index = substream->number; 137562306a36Sopenharmony_ci 137662306a36Sopenharmony_ci 137762306a36Sopenharmony_ciAfter the PCM is created, you need to set operators for each PCM stream:: 137862306a36Sopenharmony_ci 137962306a36Sopenharmony_ci snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_PLAYBACK, 138062306a36Sopenharmony_ci &snd_mychip_playback_ops); 138162306a36Sopenharmony_ci snd_pcm_set_ops(pcm, SNDRV_PCM_STREAM_CAPTURE, 138262306a36Sopenharmony_ci &snd_mychip_capture_ops); 138362306a36Sopenharmony_ci 138462306a36Sopenharmony_ciThe operators are defined typically like this:: 138562306a36Sopenharmony_ci 138662306a36Sopenharmony_ci static struct snd_pcm_ops snd_mychip_playback_ops = { 138762306a36Sopenharmony_ci .open = snd_mychip_pcm_open, 138862306a36Sopenharmony_ci .close = snd_mychip_pcm_close, 138962306a36Sopenharmony_ci .hw_params = snd_mychip_pcm_hw_params, 139062306a36Sopenharmony_ci .hw_free = snd_mychip_pcm_hw_free, 139162306a36Sopenharmony_ci .prepare = snd_mychip_pcm_prepare, 139262306a36Sopenharmony_ci .trigger = snd_mychip_pcm_trigger, 139362306a36Sopenharmony_ci .pointer = snd_mychip_pcm_pointer, 139462306a36Sopenharmony_ci }; 139562306a36Sopenharmony_ci 139662306a36Sopenharmony_ciAll the callbacks are described in the Operators_ subsection. 139762306a36Sopenharmony_ci 139862306a36Sopenharmony_ciAfter setting the operators, you probably will want to pre-allocate the 139962306a36Sopenharmony_cibuffer and set up the managed allocation mode. 140062306a36Sopenharmony_ciFor that, simply call the following:: 140162306a36Sopenharmony_ci 140262306a36Sopenharmony_ci snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV, 140362306a36Sopenharmony_ci &chip->pci->dev, 140462306a36Sopenharmony_ci 64*1024, 64*1024); 140562306a36Sopenharmony_ci 140662306a36Sopenharmony_ciIt will allocate a buffer up to 64kB by default. Buffer management 140762306a36Sopenharmony_cidetails will be described in the later section `Buffer and Memory 140862306a36Sopenharmony_ciManagement`_. 140962306a36Sopenharmony_ci 141062306a36Sopenharmony_ciAdditionally, you can set some extra information for this PCM in 141162306a36Sopenharmony_ci``pcm->info_flags``. The available values are defined as 141262306a36Sopenharmony_ci``SNDRV_PCM_INFO_XXX`` in ``<sound/asound.h>``, which is used for the 141362306a36Sopenharmony_cihardware definition (described later). When your soundchip supports only 141462306a36Sopenharmony_cihalf-duplex, specify it like this:: 141562306a36Sopenharmony_ci 141662306a36Sopenharmony_ci pcm->info_flags = SNDRV_PCM_INFO_HALF_DUPLEX; 141762306a36Sopenharmony_ci 141862306a36Sopenharmony_ci 141962306a36Sopenharmony_ci... And the Destructor? 142062306a36Sopenharmony_ci----------------------- 142162306a36Sopenharmony_ci 142262306a36Sopenharmony_ciThe destructor for a PCM instance is not always necessary. Since the PCM 142362306a36Sopenharmony_cidevice will be released by the middle layer code automatically, you 142462306a36Sopenharmony_cidon't have to call the destructor explicitly. 142562306a36Sopenharmony_ci 142662306a36Sopenharmony_ciThe destructor would be necessary if you created special records 142762306a36Sopenharmony_ciinternally and needed to release them. In such a case, set the 142862306a36Sopenharmony_cidestructor function to ``pcm->private_free``:: 142962306a36Sopenharmony_ci 143062306a36Sopenharmony_ci static void mychip_pcm_free(struct snd_pcm *pcm) 143162306a36Sopenharmony_ci { 143262306a36Sopenharmony_ci struct mychip *chip = snd_pcm_chip(pcm); 143362306a36Sopenharmony_ci /* free your own data */ 143462306a36Sopenharmony_ci kfree(chip->my_private_pcm_data); 143562306a36Sopenharmony_ci /* do what you like else */ 143662306a36Sopenharmony_ci .... 143762306a36Sopenharmony_ci } 143862306a36Sopenharmony_ci 143962306a36Sopenharmony_ci static int snd_mychip_new_pcm(struct mychip *chip) 144062306a36Sopenharmony_ci { 144162306a36Sopenharmony_ci struct snd_pcm *pcm; 144262306a36Sopenharmony_ci .... 144362306a36Sopenharmony_ci /* allocate your own data */ 144462306a36Sopenharmony_ci chip->my_private_pcm_data = kmalloc(...); 144562306a36Sopenharmony_ci /* set the destructor */ 144662306a36Sopenharmony_ci pcm->private_data = chip; 144762306a36Sopenharmony_ci pcm->private_free = mychip_pcm_free; 144862306a36Sopenharmony_ci .... 144962306a36Sopenharmony_ci } 145062306a36Sopenharmony_ci 145162306a36Sopenharmony_ci 145262306a36Sopenharmony_ci 145362306a36Sopenharmony_ciRuntime Pointer - The Chest of PCM Information 145462306a36Sopenharmony_ci---------------------------------------------- 145562306a36Sopenharmony_ci 145662306a36Sopenharmony_ciWhen the PCM substream is opened, a PCM runtime instance is allocated 145762306a36Sopenharmony_ciand assigned to the substream. This pointer is accessible via 145862306a36Sopenharmony_ci``substream->runtime``. This runtime pointer holds most information you 145962306a36Sopenharmony_cineed to control the PCM: a copy of hw_params and sw_params 146062306a36Sopenharmony_ciconfigurations, the buffer pointers, mmap records, spinlocks, etc. 146162306a36Sopenharmony_ci 146262306a36Sopenharmony_ciThe definition of runtime instance is found in ``<sound/pcm.h>``. Here 146362306a36Sopenharmony_ciis the relevant part of this file:: 146462306a36Sopenharmony_ci 146562306a36Sopenharmony_ci struct _snd_pcm_runtime { 146662306a36Sopenharmony_ci /* -- Status -- */ 146762306a36Sopenharmony_ci struct snd_pcm_substream *trigger_master; 146862306a36Sopenharmony_ci snd_timestamp_t trigger_tstamp; /* trigger timestamp */ 146962306a36Sopenharmony_ci int overrange; 147062306a36Sopenharmony_ci snd_pcm_uframes_t avail_max; 147162306a36Sopenharmony_ci snd_pcm_uframes_t hw_ptr_base; /* Position at buffer restart */ 147262306a36Sopenharmony_ci snd_pcm_uframes_t hw_ptr_interrupt; /* Position at interrupt time*/ 147362306a36Sopenharmony_ci 147462306a36Sopenharmony_ci /* -- HW params -- */ 147562306a36Sopenharmony_ci snd_pcm_access_t access; /* access mode */ 147662306a36Sopenharmony_ci snd_pcm_format_t format; /* SNDRV_PCM_FORMAT_* */ 147762306a36Sopenharmony_ci snd_pcm_subformat_t subformat; /* subformat */ 147862306a36Sopenharmony_ci unsigned int rate; /* rate in Hz */ 147962306a36Sopenharmony_ci unsigned int channels; /* channels */ 148062306a36Sopenharmony_ci snd_pcm_uframes_t period_size; /* period size */ 148162306a36Sopenharmony_ci unsigned int periods; /* periods */ 148262306a36Sopenharmony_ci snd_pcm_uframes_t buffer_size; /* buffer size */ 148362306a36Sopenharmony_ci unsigned int tick_time; /* tick time */ 148462306a36Sopenharmony_ci snd_pcm_uframes_t min_align; /* Min alignment for the format */ 148562306a36Sopenharmony_ci size_t byte_align; 148662306a36Sopenharmony_ci unsigned int frame_bits; 148762306a36Sopenharmony_ci unsigned int sample_bits; 148862306a36Sopenharmony_ci unsigned int info; 148962306a36Sopenharmony_ci unsigned int rate_num; 149062306a36Sopenharmony_ci unsigned int rate_den; 149162306a36Sopenharmony_ci 149262306a36Sopenharmony_ci /* -- SW params -- */ 149362306a36Sopenharmony_ci struct timespec tstamp_mode; /* mmap timestamp is updated */ 149462306a36Sopenharmony_ci unsigned int period_step; 149562306a36Sopenharmony_ci unsigned int sleep_min; /* min ticks to sleep */ 149662306a36Sopenharmony_ci snd_pcm_uframes_t start_threshold; 149762306a36Sopenharmony_ci /* 149862306a36Sopenharmony_ci * The following two thresholds alleviate playback buffer underruns; when 149962306a36Sopenharmony_ci * hw_avail drops below the threshold, the respective action is triggered: 150062306a36Sopenharmony_ci */ 150162306a36Sopenharmony_ci snd_pcm_uframes_t stop_threshold; /* - stop playback */ 150262306a36Sopenharmony_ci snd_pcm_uframes_t silence_threshold; /* - pre-fill buffer with silence */ 150362306a36Sopenharmony_ci snd_pcm_uframes_t silence_size; /* max size of silence pre-fill; when >= boundary, 150462306a36Sopenharmony_ci * fill played area with silence immediately */ 150562306a36Sopenharmony_ci snd_pcm_uframes_t boundary; /* pointers wrap point */ 150662306a36Sopenharmony_ci 150762306a36Sopenharmony_ci /* internal data of auto-silencer */ 150862306a36Sopenharmony_ci snd_pcm_uframes_t silence_start; /* starting pointer to silence area */ 150962306a36Sopenharmony_ci snd_pcm_uframes_t silence_filled; /* size filled with silence */ 151062306a36Sopenharmony_ci 151162306a36Sopenharmony_ci snd_pcm_sync_id_t sync; /* hardware synchronization ID */ 151262306a36Sopenharmony_ci 151362306a36Sopenharmony_ci /* -- mmap -- */ 151462306a36Sopenharmony_ci volatile struct snd_pcm_mmap_status *status; 151562306a36Sopenharmony_ci volatile struct snd_pcm_mmap_control *control; 151662306a36Sopenharmony_ci atomic_t mmap_count; 151762306a36Sopenharmony_ci 151862306a36Sopenharmony_ci /* -- locking / scheduling -- */ 151962306a36Sopenharmony_ci spinlock_t lock; 152062306a36Sopenharmony_ci wait_queue_head_t sleep; 152162306a36Sopenharmony_ci struct timer_list tick_timer; 152262306a36Sopenharmony_ci struct fasync_struct *fasync; 152362306a36Sopenharmony_ci 152462306a36Sopenharmony_ci /* -- private section -- */ 152562306a36Sopenharmony_ci void *private_data; 152662306a36Sopenharmony_ci void (*private_free)(struct snd_pcm_runtime *runtime); 152762306a36Sopenharmony_ci 152862306a36Sopenharmony_ci /* -- hardware description -- */ 152962306a36Sopenharmony_ci struct snd_pcm_hardware hw; 153062306a36Sopenharmony_ci struct snd_pcm_hw_constraints hw_constraints; 153162306a36Sopenharmony_ci 153262306a36Sopenharmony_ci /* -- timer -- */ 153362306a36Sopenharmony_ci unsigned int timer_resolution; /* timer resolution */ 153462306a36Sopenharmony_ci 153562306a36Sopenharmony_ci /* -- DMA -- */ 153662306a36Sopenharmony_ci unsigned char *dma_area; /* DMA area */ 153762306a36Sopenharmony_ci dma_addr_t dma_addr; /* physical bus address (not accessible from main CPU) */ 153862306a36Sopenharmony_ci size_t dma_bytes; /* size of DMA area */ 153962306a36Sopenharmony_ci 154062306a36Sopenharmony_ci struct snd_dma_buffer *dma_buffer_p; /* allocated buffer */ 154162306a36Sopenharmony_ci 154262306a36Sopenharmony_ci #if defined(CONFIG_SND_PCM_OSS) || defined(CONFIG_SND_PCM_OSS_MODULE) 154362306a36Sopenharmony_ci /* -- OSS things -- */ 154462306a36Sopenharmony_ci struct snd_pcm_oss_runtime oss; 154562306a36Sopenharmony_ci #endif 154662306a36Sopenharmony_ci }; 154762306a36Sopenharmony_ci 154862306a36Sopenharmony_ci 154962306a36Sopenharmony_ciFor the operators (callbacks) of each sound driver, most of these 155062306a36Sopenharmony_cirecords are supposed to be read-only. Only the PCM middle-layer changes 155162306a36Sopenharmony_ci/ updates them. The exceptions are the hardware description (hw) DMA 155262306a36Sopenharmony_cibuffer information and the private data. Besides, if you use the 155362306a36Sopenharmony_cistandard managed buffer allocation mode, you don't need to set the 155462306a36Sopenharmony_ciDMA buffer information by yourself. 155562306a36Sopenharmony_ci 155662306a36Sopenharmony_ciIn the sections below, important records are explained. 155762306a36Sopenharmony_ci 155862306a36Sopenharmony_ciHardware Description 155962306a36Sopenharmony_ci~~~~~~~~~~~~~~~~~~~~ 156062306a36Sopenharmony_ci 156162306a36Sopenharmony_ciThe hardware descriptor (struct snd_pcm_hardware) contains the definitions of 156262306a36Sopenharmony_cithe fundamental hardware configuration. Above all, you'll need to define this 156362306a36Sopenharmony_ciin the `PCM open callback`_. Note that the runtime instance holds a copy of 156462306a36Sopenharmony_cithe descriptor, not a pointer to the existing descriptor. That is, 156562306a36Sopenharmony_ciin the open callback, you can modify the copied descriptor 156662306a36Sopenharmony_ci(``runtime->hw``) as you need. For example, if the maximum number of 156762306a36Sopenharmony_cichannels is 1 only on some chip models, you can still use the same 156862306a36Sopenharmony_cihardware descriptor and change the channels_max later:: 156962306a36Sopenharmony_ci 157062306a36Sopenharmony_ci struct snd_pcm_runtime *runtime = substream->runtime; 157162306a36Sopenharmony_ci ... 157262306a36Sopenharmony_ci runtime->hw = snd_mychip_playback_hw; /* common definition */ 157362306a36Sopenharmony_ci if (chip->model == VERY_OLD_ONE) 157462306a36Sopenharmony_ci runtime->hw.channels_max = 1; 157562306a36Sopenharmony_ci 157662306a36Sopenharmony_ciTypically, you'll have a hardware descriptor as below:: 157762306a36Sopenharmony_ci 157862306a36Sopenharmony_ci static struct snd_pcm_hardware snd_mychip_playback_hw = { 157962306a36Sopenharmony_ci .info = (SNDRV_PCM_INFO_MMAP | 158062306a36Sopenharmony_ci SNDRV_PCM_INFO_INTERLEAVED | 158162306a36Sopenharmony_ci SNDRV_PCM_INFO_BLOCK_TRANSFER | 158262306a36Sopenharmony_ci SNDRV_PCM_INFO_MMAP_VALID), 158362306a36Sopenharmony_ci .formats = SNDRV_PCM_FMTBIT_S16_LE, 158462306a36Sopenharmony_ci .rates = SNDRV_PCM_RATE_8000_48000, 158562306a36Sopenharmony_ci .rate_min = 8000, 158662306a36Sopenharmony_ci .rate_max = 48000, 158762306a36Sopenharmony_ci .channels_min = 2, 158862306a36Sopenharmony_ci .channels_max = 2, 158962306a36Sopenharmony_ci .buffer_bytes_max = 32768, 159062306a36Sopenharmony_ci .period_bytes_min = 4096, 159162306a36Sopenharmony_ci .period_bytes_max = 32768, 159262306a36Sopenharmony_ci .periods_min = 1, 159362306a36Sopenharmony_ci .periods_max = 1024, 159462306a36Sopenharmony_ci }; 159562306a36Sopenharmony_ci 159662306a36Sopenharmony_ci- The ``info`` field contains the type and capabilities of this 159762306a36Sopenharmony_ci PCM. The bit flags are defined in ``<sound/asound.h>`` as 159862306a36Sopenharmony_ci ``SNDRV_PCM_INFO_XXX``. Here, at least, you have to specify whether 159962306a36Sopenharmony_ci mmap is supported and which interleaving formats are 160062306a36Sopenharmony_ci supported. When the hardware supports mmap, add the 160162306a36Sopenharmony_ci ``SNDRV_PCM_INFO_MMAP`` flag here. When the hardware supports the 160262306a36Sopenharmony_ci interleaved or the non-interleaved formats, the 160362306a36Sopenharmony_ci ``SNDRV_PCM_INFO_INTERLEAVED`` or ``SNDRV_PCM_INFO_NONINTERLEAVED`` 160462306a36Sopenharmony_ci flag must be set, respectively. If both are supported, you can set 160562306a36Sopenharmony_ci both, too. 160662306a36Sopenharmony_ci 160762306a36Sopenharmony_ci In the above example, ``MMAP_VALID`` and ``BLOCK_TRANSFER`` are 160862306a36Sopenharmony_ci specified for the OSS mmap mode. Usually both are set. Of course, 160962306a36Sopenharmony_ci ``MMAP_VALID`` is set only if mmap is really supported. 161062306a36Sopenharmony_ci 161162306a36Sopenharmony_ci The other possible flags are ``SNDRV_PCM_INFO_PAUSE`` and 161262306a36Sopenharmony_ci ``SNDRV_PCM_INFO_RESUME``. The ``PAUSE`` bit means that the PCM 161362306a36Sopenharmony_ci supports the “pause” operation, while the ``RESUME`` bit means that 161462306a36Sopenharmony_ci the PCM supports the full “suspend/resume” operation. If the 161562306a36Sopenharmony_ci ``PAUSE`` flag is set, the ``trigger`` callback below must handle 161662306a36Sopenharmony_ci the corresponding (pause push/release) commands. The suspend/resume 161762306a36Sopenharmony_ci trigger commands can be defined even without the ``RESUME`` 161862306a36Sopenharmony_ci flag. See the `Power Management`_ section for details. 161962306a36Sopenharmony_ci 162062306a36Sopenharmony_ci When the PCM substreams can be synchronized (typically, 162162306a36Sopenharmony_ci synchronized start/stop of a playback and a capture stream), you 162262306a36Sopenharmony_ci can give ``SNDRV_PCM_INFO_SYNC_START``, too. In this case, you'll 162362306a36Sopenharmony_ci need to check the linked-list of PCM substreams in the trigger 162462306a36Sopenharmony_ci callback. This will be described in a later section. 162562306a36Sopenharmony_ci 162662306a36Sopenharmony_ci- The ``formats`` field contains the bit-flags of supported formats 162762306a36Sopenharmony_ci (``SNDRV_PCM_FMTBIT_XXX``). If the hardware supports more than one 162862306a36Sopenharmony_ci format, give all or'ed bits. In the example above, the signed 16bit 162962306a36Sopenharmony_ci little-endian format is specified. 163062306a36Sopenharmony_ci 163162306a36Sopenharmony_ci- The ``rates`` field contains the bit-flags of supported rates 163262306a36Sopenharmony_ci (``SNDRV_PCM_RATE_XXX``). When the chip supports continuous rates, 163362306a36Sopenharmony_ci pass the ``CONTINUOUS`` bit additionally. The pre-defined rate bits 163462306a36Sopenharmony_ci are provided only for typical rates. If your chip supports 163562306a36Sopenharmony_ci unconventional rates, you need to add the ``KNOT`` bit and set up 163662306a36Sopenharmony_ci the hardware constraint manually (explained later). 163762306a36Sopenharmony_ci 163862306a36Sopenharmony_ci- ``rate_min`` and ``rate_max`` define the minimum and maximum sample 163962306a36Sopenharmony_ci rate. This should correspond somehow to ``rates`` bits. 164062306a36Sopenharmony_ci 164162306a36Sopenharmony_ci- ``channels_min`` and ``channels_max`` define, as you might have already 164262306a36Sopenharmony_ci expected, the minimum and maximum number of channels. 164362306a36Sopenharmony_ci 164462306a36Sopenharmony_ci- ``buffer_bytes_max`` defines the maximum buffer size in 164562306a36Sopenharmony_ci bytes. There is no ``buffer_bytes_min`` field, since it can be 164662306a36Sopenharmony_ci calculated from the minimum period size and the minimum number of 164762306a36Sopenharmony_ci periods. Meanwhile, ``period_bytes_min`` and ``period_bytes_max`` 164862306a36Sopenharmony_ci define the minimum and maximum size of the period in bytes. 164962306a36Sopenharmony_ci ``periods_max`` and ``periods_min`` define the maximum and minimum 165062306a36Sopenharmony_ci number of periods in the buffer. 165162306a36Sopenharmony_ci 165262306a36Sopenharmony_ci The “period” is a term that corresponds to a fragment in the OSS 165362306a36Sopenharmony_ci world. The period defines the point at which a PCM interrupt is 165462306a36Sopenharmony_ci generated. This point strongly depends on the hardware. Generally, 165562306a36Sopenharmony_ci a smaller period size will give you more interrupts, which results 165662306a36Sopenharmony_ci in being able to fill/drain the buffer more timely. In the case of 165762306a36Sopenharmony_ci capture, this size defines the input latency. On the other hand, 165862306a36Sopenharmony_ci the whole buffer size defines the output latency for the playback 165962306a36Sopenharmony_ci direction. 166062306a36Sopenharmony_ci 166162306a36Sopenharmony_ci- There is also a field ``fifo_size``. This specifies the size of the 166262306a36Sopenharmony_ci hardware FIFO, but currently it is neither used by the drivers nor 166362306a36Sopenharmony_ci in the alsa-lib. So, you can ignore this field. 166462306a36Sopenharmony_ci 166562306a36Sopenharmony_ciPCM Configurations 166662306a36Sopenharmony_ci~~~~~~~~~~~~~~~~~~ 166762306a36Sopenharmony_ci 166862306a36Sopenharmony_ciOk, let's go back again to the PCM runtime records. The most 166962306a36Sopenharmony_cifrequently referred records in the runtime instance are the PCM 167062306a36Sopenharmony_ciconfigurations. The PCM configurations are stored in the runtime 167162306a36Sopenharmony_ciinstance after the application sends ``hw_params`` data via 167262306a36Sopenharmony_cialsa-lib. There are many fields copied from hw_params and sw_params 167362306a36Sopenharmony_cistructs. For example, ``format`` holds the format type chosen by the 167462306a36Sopenharmony_ciapplication. This field contains the enum value 167562306a36Sopenharmony_ci``SNDRV_PCM_FORMAT_XXX``. 167662306a36Sopenharmony_ci 167762306a36Sopenharmony_ciOne thing to be noted is that the configured buffer and period sizes 167862306a36Sopenharmony_ciare stored in “frames” in the runtime. In the ALSA world, ``1 frame = 167962306a36Sopenharmony_cichannels \* samples-size``. For conversion between frames and bytes, 168062306a36Sopenharmony_ciyou can use the :c:func:`frames_to_bytes()` and 168162306a36Sopenharmony_ci:c:func:`bytes_to_frames()` helper functions:: 168262306a36Sopenharmony_ci 168362306a36Sopenharmony_ci period_bytes = frames_to_bytes(runtime, runtime->period_size); 168462306a36Sopenharmony_ci 168562306a36Sopenharmony_ciAlso, many software parameters (sw_params) are stored in frames, too. 168662306a36Sopenharmony_ciPlease check the type of the field. ``snd_pcm_uframes_t`` is for 168762306a36Sopenharmony_ciframes as unsigned integer while ``snd_pcm_sframes_t`` is for 168862306a36Sopenharmony_ciframes as signed integer. 168962306a36Sopenharmony_ci 169062306a36Sopenharmony_ciDMA Buffer Information 169162306a36Sopenharmony_ci~~~~~~~~~~~~~~~~~~~~~~ 169262306a36Sopenharmony_ci 169362306a36Sopenharmony_ciThe DMA buffer is defined by the following four fields: ``dma_area``, 169462306a36Sopenharmony_ci``dma_addr``, ``dma_bytes`` and ``dma_private``. ``dma_area`` 169562306a36Sopenharmony_ciholds the buffer pointer (the logical address). You can call 169662306a36Sopenharmony_ci:c:func:`memcpy()` from/to this pointer. Meanwhile, ``dma_addr`` holds 169762306a36Sopenharmony_cithe physical address of the buffer. This field is specified only when 169862306a36Sopenharmony_cithe buffer is a linear buffer. ``dma_bytes`` holds the size of the 169962306a36Sopenharmony_cibuffer in bytes. ``dma_private`` is used for the ALSA DMA allocator. 170062306a36Sopenharmony_ci 170162306a36Sopenharmony_ciIf you use either the managed buffer allocation mode or the standard 170262306a36Sopenharmony_ciAPI function :c:func:`snd_pcm_lib_malloc_pages()` for allocating the buffer, 170362306a36Sopenharmony_cithese fields are set by the ALSA middle layer, and you should *not* 170462306a36Sopenharmony_cichange them by yourself. You can read them but not write them. On the 170562306a36Sopenharmony_ciother hand, if you want to allocate the buffer by yourself, you'll 170662306a36Sopenharmony_cineed to manage it in the hw_params callback. At least, ``dma_bytes`` is 170762306a36Sopenharmony_cimandatory. ``dma_area`` is necessary when the buffer is mmapped. If 170862306a36Sopenharmony_ciyour driver doesn't support mmap, this field is not 170962306a36Sopenharmony_cinecessary. ``dma_addr`` is also optional. You can use dma_private as 171062306a36Sopenharmony_ciyou like, too. 171162306a36Sopenharmony_ci 171262306a36Sopenharmony_ciRunning Status 171362306a36Sopenharmony_ci~~~~~~~~~~~~~~ 171462306a36Sopenharmony_ci 171562306a36Sopenharmony_ciThe running status can be referred via ``runtime->status``. This is 171662306a36Sopenharmony_cia pointer to a struct snd_pcm_mmap_status record. 171762306a36Sopenharmony_ciFor example, you can get the current 171862306a36Sopenharmony_ciDMA hardware pointer via ``runtime->status->hw_ptr``. 171962306a36Sopenharmony_ci 172062306a36Sopenharmony_ciThe DMA application pointer can be referred via ``runtime->control``, 172162306a36Sopenharmony_ciwhich points to a struct snd_pcm_mmap_control record. 172262306a36Sopenharmony_ciHowever, accessing this value directly is not recommended. 172362306a36Sopenharmony_ci 172462306a36Sopenharmony_ciPrivate Data 172562306a36Sopenharmony_ci~~~~~~~~~~~~ 172662306a36Sopenharmony_ci 172762306a36Sopenharmony_ciYou can allocate a record for the substream and store it in 172862306a36Sopenharmony_ci``runtime->private_data``. Usually, this is done in the `PCM open 172962306a36Sopenharmony_cicallback`_. Don't mix this with ``pcm->private_data``. The 173062306a36Sopenharmony_ci``pcm->private_data`` usually points to the chip instance assigned 173162306a36Sopenharmony_cistatically at creation time of the PCM device, while 173262306a36Sopenharmony_ci``runtime->private_data`` 173362306a36Sopenharmony_cipoints to a dynamic data structure created in the PCM open 173462306a36Sopenharmony_cicallback:: 173562306a36Sopenharmony_ci 173662306a36Sopenharmony_ci static int snd_xxx_open(struct snd_pcm_substream *substream) 173762306a36Sopenharmony_ci { 173862306a36Sopenharmony_ci struct my_pcm_data *data; 173962306a36Sopenharmony_ci .... 174062306a36Sopenharmony_ci data = kmalloc(sizeof(*data), GFP_KERNEL); 174162306a36Sopenharmony_ci substream->runtime->private_data = data; 174262306a36Sopenharmony_ci .... 174362306a36Sopenharmony_ci } 174462306a36Sopenharmony_ci 174562306a36Sopenharmony_ci 174662306a36Sopenharmony_ciThe allocated object must be released in the `close callback`_. 174762306a36Sopenharmony_ci 174862306a36Sopenharmony_ciOperators 174962306a36Sopenharmony_ci--------- 175062306a36Sopenharmony_ci 175162306a36Sopenharmony_ciOK, now let me give details about each PCM callback (``ops``). In 175262306a36Sopenharmony_cigeneral, every callback must return 0 if successful, or a negative 175362306a36Sopenharmony_cierror number such as ``-EINVAL``. To choose an appropriate error 175462306a36Sopenharmony_cinumber, it is advised to check what value other parts of the kernel 175562306a36Sopenharmony_cireturn when the same kind of request fails. 175662306a36Sopenharmony_ci 175762306a36Sopenharmony_ciEach callback function takes at least one argument containing a 175862306a36Sopenharmony_cistruct snd_pcm_substream pointer. To retrieve the chip 175962306a36Sopenharmony_cirecord from the given substream instance, you can use the following 176062306a36Sopenharmony_cimacro:: 176162306a36Sopenharmony_ci 176262306a36Sopenharmony_ci int xxx(...) { 176362306a36Sopenharmony_ci struct mychip *chip = snd_pcm_substream_chip(substream); 176462306a36Sopenharmony_ci .... 176562306a36Sopenharmony_ci } 176662306a36Sopenharmony_ci 176762306a36Sopenharmony_ciThe macro reads ``substream->private_data``, which is a copy of 176862306a36Sopenharmony_ci``pcm->private_data``. You can override the former if you need to 176962306a36Sopenharmony_ciassign different data records per PCM substream. For example, the 177062306a36Sopenharmony_cicmi8330 driver assigns different ``private_data`` for playback and 177162306a36Sopenharmony_cicapture directions, because it uses two different codecs (SB- and 177262306a36Sopenharmony_ciAD-compatible) for different directions. 177362306a36Sopenharmony_ci 177462306a36Sopenharmony_ciPCM open callback 177562306a36Sopenharmony_ci~~~~~~~~~~~~~~~~~ 177662306a36Sopenharmony_ci 177762306a36Sopenharmony_ci:: 177862306a36Sopenharmony_ci 177962306a36Sopenharmony_ci static int snd_xxx_open(struct snd_pcm_substream *substream); 178062306a36Sopenharmony_ci 178162306a36Sopenharmony_ciThis is called when a PCM substream is opened. 178262306a36Sopenharmony_ci 178362306a36Sopenharmony_ciAt least, here you have to initialize the ``runtime->hw`` 178462306a36Sopenharmony_cirecord. Typically, this is done like this:: 178562306a36Sopenharmony_ci 178662306a36Sopenharmony_ci static int snd_xxx_open(struct snd_pcm_substream *substream) 178762306a36Sopenharmony_ci { 178862306a36Sopenharmony_ci struct mychip *chip = snd_pcm_substream_chip(substream); 178962306a36Sopenharmony_ci struct snd_pcm_runtime *runtime = substream->runtime; 179062306a36Sopenharmony_ci 179162306a36Sopenharmony_ci runtime->hw = snd_mychip_playback_hw; 179262306a36Sopenharmony_ci return 0; 179362306a36Sopenharmony_ci } 179462306a36Sopenharmony_ci 179562306a36Sopenharmony_ciwhere ``snd_mychip_playback_hw`` is the pre-defined hardware 179662306a36Sopenharmony_cidescription. 179762306a36Sopenharmony_ci 179862306a36Sopenharmony_ciYou can allocate private data in this callback, as described in the 179962306a36Sopenharmony_ci`Private Data`_ section. 180062306a36Sopenharmony_ci 180162306a36Sopenharmony_ciIf the hardware configuration needs more constraints, set the hardware 180262306a36Sopenharmony_ciconstraints here, too. See Constraints_ for more details. 180362306a36Sopenharmony_ci 180462306a36Sopenharmony_ciclose callback 180562306a36Sopenharmony_ci~~~~~~~~~~~~~~ 180662306a36Sopenharmony_ci 180762306a36Sopenharmony_ci:: 180862306a36Sopenharmony_ci 180962306a36Sopenharmony_ci static int snd_xxx_close(struct snd_pcm_substream *substream); 181062306a36Sopenharmony_ci 181162306a36Sopenharmony_ci 181262306a36Sopenharmony_ciObviously, this is called when a PCM substream is closed. 181362306a36Sopenharmony_ci 181462306a36Sopenharmony_ciAny private instance for a PCM substream allocated in the ``open`` 181562306a36Sopenharmony_cicallback will be released here:: 181662306a36Sopenharmony_ci 181762306a36Sopenharmony_ci static int snd_xxx_close(struct snd_pcm_substream *substream) 181862306a36Sopenharmony_ci { 181962306a36Sopenharmony_ci .... 182062306a36Sopenharmony_ci kfree(substream->runtime->private_data); 182162306a36Sopenharmony_ci .... 182262306a36Sopenharmony_ci } 182362306a36Sopenharmony_ci 182462306a36Sopenharmony_ciioctl callback 182562306a36Sopenharmony_ci~~~~~~~~~~~~~~ 182662306a36Sopenharmony_ci 182762306a36Sopenharmony_ciThis is used for any special call to PCM ioctls. But usually you can 182862306a36Sopenharmony_cileave it NULL, then the PCM core calls the generic ioctl callback 182962306a36Sopenharmony_cifunction :c:func:`snd_pcm_lib_ioctl()`. If you need to deal with a 183062306a36Sopenharmony_ciunique setup of channel info or reset procedure, you can pass your own 183162306a36Sopenharmony_cicallback function here. 183262306a36Sopenharmony_ci 183362306a36Sopenharmony_cihw_params callback 183462306a36Sopenharmony_ci~~~~~~~~~~~~~~~~~~~ 183562306a36Sopenharmony_ci 183662306a36Sopenharmony_ci:: 183762306a36Sopenharmony_ci 183862306a36Sopenharmony_ci static int snd_xxx_hw_params(struct snd_pcm_substream *substream, 183962306a36Sopenharmony_ci struct snd_pcm_hw_params *hw_params); 184062306a36Sopenharmony_ci 184162306a36Sopenharmony_ciThis is called when the hardware parameters (``hw_params``) are set up 184262306a36Sopenharmony_ciby the application, that is, once when the buffer size, the period 184362306a36Sopenharmony_cisize, the format, etc. are defined for the PCM substream. 184462306a36Sopenharmony_ci 184562306a36Sopenharmony_ciMany hardware setups should be done in this callback, including the 184662306a36Sopenharmony_ciallocation of buffers. 184762306a36Sopenharmony_ci 184862306a36Sopenharmony_ciParameters to be initialized are retrieved by the 184962306a36Sopenharmony_ci:c:func:`params_xxx()` macros. 185062306a36Sopenharmony_ci 185162306a36Sopenharmony_ciWhen you choose managed buffer allocation mode for the substream, 185262306a36Sopenharmony_cia buffer is already allocated before this callback gets 185362306a36Sopenharmony_cicalled. Alternatively, you can call a helper function below for 185462306a36Sopenharmony_ciallocating the buffer:: 185562306a36Sopenharmony_ci 185662306a36Sopenharmony_ci snd_pcm_lib_malloc_pages(substream, params_buffer_bytes(hw_params)); 185762306a36Sopenharmony_ci 185862306a36Sopenharmony_ci:c:func:`snd_pcm_lib_malloc_pages()` is available only when the 185962306a36Sopenharmony_ciDMA buffers have been pre-allocated. See the section `Buffer Types`_ 186062306a36Sopenharmony_cifor more details. 186162306a36Sopenharmony_ci 186262306a36Sopenharmony_ciNote that this one and the ``prepare`` callback may be called multiple 186362306a36Sopenharmony_citimes per initialization. For example, the OSS emulation may call these 186462306a36Sopenharmony_cicallbacks at each change via its ioctl. 186562306a36Sopenharmony_ci 186662306a36Sopenharmony_ciThus, you need to be careful not to allocate the same buffers many 186762306a36Sopenharmony_citimes, which will lead to memory leaks! Calling the helper function 186862306a36Sopenharmony_ciabove many times is OK. It will release the previous buffer 186962306a36Sopenharmony_ciautomatically when it was already allocated. 187062306a36Sopenharmony_ci 187162306a36Sopenharmony_ciAnother note is that this callback is non-atomic (schedulable) by 187262306a36Sopenharmony_cidefault, i.e. when no ``nonatomic`` flag set. This is important, 187362306a36Sopenharmony_cibecause the ``trigger`` callback is atomic (non-schedulable). That is, 187462306a36Sopenharmony_cimutexes or any schedule-related functions are not available in the 187562306a36Sopenharmony_ci``trigger`` callback. Please see the subsection Atomicity_ for 187662306a36Sopenharmony_cidetails. 187762306a36Sopenharmony_ci 187862306a36Sopenharmony_cihw_free callback 187962306a36Sopenharmony_ci~~~~~~~~~~~~~~~~~ 188062306a36Sopenharmony_ci 188162306a36Sopenharmony_ci:: 188262306a36Sopenharmony_ci 188362306a36Sopenharmony_ci static int snd_xxx_hw_free(struct snd_pcm_substream *substream); 188462306a36Sopenharmony_ci 188562306a36Sopenharmony_ciThis is called to release the resources allocated via 188662306a36Sopenharmony_ci``hw_params``. 188762306a36Sopenharmony_ci 188862306a36Sopenharmony_ciThis function is always called before the close callback is called. 188962306a36Sopenharmony_ciAlso, the callback may be called multiple times, too. Keep track 189062306a36Sopenharmony_ciwhether each resource was already released. 189162306a36Sopenharmony_ci 189262306a36Sopenharmony_ciWhen you have chosen managed buffer allocation mode for the PCM 189362306a36Sopenharmony_cisubstream, the allocated PCM buffer will be automatically released 189462306a36Sopenharmony_ciafter this callback gets called. Otherwise you'll have to release the 189562306a36Sopenharmony_cibuffer manually. Typically, when the buffer was allocated from the 189662306a36Sopenharmony_cipre-allocated pool, you can use the standard API function 189762306a36Sopenharmony_ci:c:func:`snd_pcm_lib_malloc_pages()` like:: 189862306a36Sopenharmony_ci 189962306a36Sopenharmony_ci snd_pcm_lib_free_pages(substream); 190062306a36Sopenharmony_ci 190162306a36Sopenharmony_ciprepare callback 190262306a36Sopenharmony_ci~~~~~~~~~~~~~~~~ 190362306a36Sopenharmony_ci 190462306a36Sopenharmony_ci:: 190562306a36Sopenharmony_ci 190662306a36Sopenharmony_ci static int snd_xxx_prepare(struct snd_pcm_substream *substream); 190762306a36Sopenharmony_ci 190862306a36Sopenharmony_ciThis callback is called when the PCM is “prepared”. You can set the 190962306a36Sopenharmony_ciformat type, sample rate, etc. here. The difference from ``hw_params`` 191062306a36Sopenharmony_ciis that the ``prepare`` callback will be called each time 191162306a36Sopenharmony_ci:c:func:`snd_pcm_prepare()` is called, i.e. when recovering after 191262306a36Sopenharmony_ciunderruns, etc. 191362306a36Sopenharmony_ci 191462306a36Sopenharmony_ciNote that this callback is non-atomic. You can use 191562306a36Sopenharmony_cischedule-related functions safely in this callback. 191662306a36Sopenharmony_ci 191762306a36Sopenharmony_ciIn this and the following callbacks, you can refer to the values via 191862306a36Sopenharmony_cithe runtime record, ``substream->runtime``. For example, to get the 191962306a36Sopenharmony_cicurrent rate, format or channels, access to ``runtime->rate``, 192062306a36Sopenharmony_ci``runtime->format`` or ``runtime->channels``, respectively. The 192162306a36Sopenharmony_ciphysical address of the allocated buffer is set to 192262306a36Sopenharmony_ci``runtime->dma_area``. The buffer and period sizes are in 192362306a36Sopenharmony_ci``runtime->buffer_size`` and ``runtime->period_size``, respectively. 192462306a36Sopenharmony_ci 192562306a36Sopenharmony_ciBe careful that this callback will be called many times at each setup, 192662306a36Sopenharmony_citoo. 192762306a36Sopenharmony_ci 192862306a36Sopenharmony_citrigger callback 192962306a36Sopenharmony_ci~~~~~~~~~~~~~~~~ 193062306a36Sopenharmony_ci 193162306a36Sopenharmony_ci:: 193262306a36Sopenharmony_ci 193362306a36Sopenharmony_ci static int snd_xxx_trigger(struct snd_pcm_substream *substream, int cmd); 193462306a36Sopenharmony_ci 193562306a36Sopenharmony_ciThis is called when the PCM is started, stopped or paused. 193662306a36Sopenharmony_ci 193762306a36Sopenharmony_ciThe action is specified in the second argument, ``SNDRV_PCM_TRIGGER_XXX`` 193862306a36Sopenharmony_cidefined in ``<sound/pcm.h>``. At least, the ``START`` 193962306a36Sopenharmony_ciand ``STOP`` commands must be defined in this callback:: 194062306a36Sopenharmony_ci 194162306a36Sopenharmony_ci switch (cmd) { 194262306a36Sopenharmony_ci case SNDRV_PCM_TRIGGER_START: 194362306a36Sopenharmony_ci /* do something to start the PCM engine */ 194462306a36Sopenharmony_ci break; 194562306a36Sopenharmony_ci case SNDRV_PCM_TRIGGER_STOP: 194662306a36Sopenharmony_ci /* do something to stop the PCM engine */ 194762306a36Sopenharmony_ci break; 194862306a36Sopenharmony_ci default: 194962306a36Sopenharmony_ci return -EINVAL; 195062306a36Sopenharmony_ci } 195162306a36Sopenharmony_ci 195262306a36Sopenharmony_ciWhen the PCM supports the pause operation (given in the info field of 195362306a36Sopenharmony_cithe hardware table), the ``PAUSE_PUSH`` and ``PAUSE_RELEASE`` commands 195462306a36Sopenharmony_cimust be handled here, too. The former is the command to pause the PCM, 195562306a36Sopenharmony_ciand the latter to restart the PCM again. 195662306a36Sopenharmony_ci 195762306a36Sopenharmony_ciWhen the PCM supports the suspend/resume operation, regardless of full 195862306a36Sopenharmony_cior partial suspend/resume support, the ``SUSPEND`` and ``RESUME`` 195962306a36Sopenharmony_cicommands must be handled, too. These commands are issued when the 196062306a36Sopenharmony_cipower-management status is changed. Obviously, the ``SUSPEND`` and 196162306a36Sopenharmony_ci``RESUME`` commands suspend and resume the PCM substream, and usually, 196262306a36Sopenharmony_cithey are identical to the ``STOP`` and ``START`` commands, respectively. 196362306a36Sopenharmony_ciSee the `Power Management`_ section for details. 196462306a36Sopenharmony_ci 196562306a36Sopenharmony_ciAs mentioned, this callback is atomic by default unless the ``nonatomic`` 196662306a36Sopenharmony_ciflag set, and you cannot call functions which may sleep. The 196762306a36Sopenharmony_ci``trigger`` callback should be as minimal as possible, just really 196862306a36Sopenharmony_citriggering the DMA. The other stuff should be initialized in 196962306a36Sopenharmony_ci``hw_params`` and ``prepare`` callbacks properly beforehand. 197062306a36Sopenharmony_ci 197162306a36Sopenharmony_cisync_stop callback 197262306a36Sopenharmony_ci~~~~~~~~~~~~~~~~~~ 197362306a36Sopenharmony_ci 197462306a36Sopenharmony_ci:: 197562306a36Sopenharmony_ci 197662306a36Sopenharmony_ci static int snd_xxx_sync_stop(struct snd_pcm_substream *substream); 197762306a36Sopenharmony_ci 197862306a36Sopenharmony_ciThis callback is optional, and NULL can be passed. It's called after 197962306a36Sopenharmony_cithe PCM core stops the stream, before it changes the stream state via 198062306a36Sopenharmony_ci``prepare``, ``hw_params`` or ``hw_free``. 198162306a36Sopenharmony_ciSince the IRQ handler might be still pending, we need to wait until 198262306a36Sopenharmony_cithe pending task finishes before moving to the next step; otherwise it 198362306a36Sopenharmony_cimight lead to a crash due to resource conflicts or access to freed 198462306a36Sopenharmony_ciresources. A typical behavior is to call a synchronization function 198562306a36Sopenharmony_cilike :c:func:`synchronize_irq()` here. 198662306a36Sopenharmony_ci 198762306a36Sopenharmony_ciFor the majority of drivers that need only a call of 198862306a36Sopenharmony_ci:c:func:`synchronize_irq()`, there is a simpler setup, too. 198962306a36Sopenharmony_ciWhile keeping the ``sync_stop`` PCM callback NULL, the driver can set 199062306a36Sopenharmony_cithe ``card->sync_irq`` field to the returned interrupt number after 199162306a36Sopenharmony_cirequesting an IRQ, instead. Then PCM core will call 199262306a36Sopenharmony_ci:c:func:`synchronize_irq()` with the given IRQ appropriately. 199362306a36Sopenharmony_ci 199462306a36Sopenharmony_ciIf the IRQ handler is released by the card destructor, you don't need 199562306a36Sopenharmony_cito clear ``card->sync_irq``, as the card itself is being released. 199662306a36Sopenharmony_ciSo, usually you'll need to add just a single line for assigning 199762306a36Sopenharmony_ci``card->sync_irq`` in the driver code unless the driver re-acquires 199862306a36Sopenharmony_cithe IRQ. When the driver frees and re-acquires the IRQ dynamically 199962306a36Sopenharmony_ci(e.g. for suspend/resume), it needs to clear and re-set 200062306a36Sopenharmony_ci``card->sync_irq`` again appropriately. 200162306a36Sopenharmony_ci 200262306a36Sopenharmony_cipointer callback 200362306a36Sopenharmony_ci~~~~~~~~~~~~~~~~ 200462306a36Sopenharmony_ci 200562306a36Sopenharmony_ci:: 200662306a36Sopenharmony_ci 200762306a36Sopenharmony_ci static snd_pcm_uframes_t snd_xxx_pointer(struct snd_pcm_substream *substream) 200862306a36Sopenharmony_ci 200962306a36Sopenharmony_ciThis callback is called when the PCM middle layer inquires the current 201062306a36Sopenharmony_cihardware position in the buffer. The position must be returned in 201162306a36Sopenharmony_ciframes, ranging from 0 to ``buffer_size - 1``. 201262306a36Sopenharmony_ci 201362306a36Sopenharmony_ciThis is usually called from the buffer-update routine in the PCM 201462306a36Sopenharmony_cimiddle layer, which is invoked when :c:func:`snd_pcm_period_elapsed()` 201562306a36Sopenharmony_ciis called by the interrupt routine. Then the PCM middle layer updates 201662306a36Sopenharmony_cithe position and calculates the available space, and wakes up the 201762306a36Sopenharmony_cisleeping poll threads, etc. 201862306a36Sopenharmony_ci 201962306a36Sopenharmony_ciThis callback is also atomic by default. 202062306a36Sopenharmony_ci 202162306a36Sopenharmony_cicopy and fill_silence ops 202262306a36Sopenharmony_ci~~~~~~~~~~~~~~~~~~~~~~~~~ 202362306a36Sopenharmony_ci 202462306a36Sopenharmony_ciThese callbacks are not mandatory, and can be omitted in most cases. 202562306a36Sopenharmony_ciThese callbacks are used when the hardware buffer cannot be in the 202662306a36Sopenharmony_cinormal memory space. Some chips have their own buffer in the hardware 202762306a36Sopenharmony_ciwhich is not mappable. In such a case, you have to transfer the data 202862306a36Sopenharmony_cimanually from the memory buffer to the hardware buffer. Or, if the 202962306a36Sopenharmony_cibuffer is non-contiguous on both physical and virtual memory spaces, 203062306a36Sopenharmony_cithese callbacks must be defined, too. 203162306a36Sopenharmony_ci 203262306a36Sopenharmony_ciIf these two callbacks are defined, copy and set-silence operations 203362306a36Sopenharmony_ciare done by them. The details will be described in the later section 203462306a36Sopenharmony_ci`Buffer and Memory Management`_. 203562306a36Sopenharmony_ci 203662306a36Sopenharmony_ciack callback 203762306a36Sopenharmony_ci~~~~~~~~~~~~ 203862306a36Sopenharmony_ci 203962306a36Sopenharmony_ciThis callback is also not mandatory. This callback is called when the 204062306a36Sopenharmony_ci``appl_ptr`` is updated in read or write operations. Some drivers like 204162306a36Sopenharmony_ciemu10k1-fx and cs46xx need to track the current ``appl_ptr`` for the 204262306a36Sopenharmony_ciinternal buffer, and this callback is useful only for such a purpose. 204362306a36Sopenharmony_ci 204462306a36Sopenharmony_ciThe callback function may return 0 or a negative error. When the 204562306a36Sopenharmony_cireturn value is ``-EPIPE``, PCM core treats that as a buffer XRUN, 204662306a36Sopenharmony_ciand changes the state to ``SNDRV_PCM_STATE_XRUN`` automatically. 204762306a36Sopenharmony_ci 204862306a36Sopenharmony_ciThis callback is atomic by default. 204962306a36Sopenharmony_ci 205062306a36Sopenharmony_cipage callback 205162306a36Sopenharmony_ci~~~~~~~~~~~~~ 205262306a36Sopenharmony_ci 205362306a36Sopenharmony_ciThis callback is optional too. The mmap calls this callback to get the 205462306a36Sopenharmony_cipage fault address. 205562306a36Sopenharmony_ci 205662306a36Sopenharmony_ciYou need no special callback for the standard SG-buffer or vmalloc- 205762306a36Sopenharmony_cibuffer. Hence this callback should be rarely used. 205862306a36Sopenharmony_ci 205962306a36Sopenharmony_cimmap callback 206062306a36Sopenharmony_ci~~~~~~~~~~~~~ 206162306a36Sopenharmony_ci 206262306a36Sopenharmony_ciThis is another optional callback for controlling mmap behavior. 206362306a36Sopenharmony_ciWhen defined, the PCM core calls this callback when a page is 206462306a36Sopenharmony_cimemory-mapped, instead of using the standard helper. 206562306a36Sopenharmony_ciIf you need special handling (due to some architecture or 206662306a36Sopenharmony_cidevice-specific issues), implement everything here as you like. 206762306a36Sopenharmony_ci 206862306a36Sopenharmony_ci 206962306a36Sopenharmony_ciPCM Interrupt Handler 207062306a36Sopenharmony_ci--------------------- 207162306a36Sopenharmony_ci 207262306a36Sopenharmony_ciThe remainder of the PCM stuff is the PCM interrupt handler. The role 207362306a36Sopenharmony_ciof the PCM 207462306a36Sopenharmony_ciinterrupt handler in the sound driver is to update the buffer position 207562306a36Sopenharmony_ciand to tell the PCM middle layer when the buffer position goes across 207662306a36Sopenharmony_cithe specified period boundary. To inform about this, call the 207762306a36Sopenharmony_ci:c:func:`snd_pcm_period_elapsed()` function. 207862306a36Sopenharmony_ci 207962306a36Sopenharmony_ciThere are several ways sound chips can generate interrupts. 208062306a36Sopenharmony_ci 208162306a36Sopenharmony_ciInterrupts at the period (fragment) boundary 208262306a36Sopenharmony_ci~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 208362306a36Sopenharmony_ci 208462306a36Sopenharmony_ciThis is the most frequently found type: the hardware generates an 208562306a36Sopenharmony_ciinterrupt at each period boundary. In this case, you can call 208662306a36Sopenharmony_ci:c:func:`snd_pcm_period_elapsed()` at each interrupt. 208762306a36Sopenharmony_ci 208862306a36Sopenharmony_ci:c:func:`snd_pcm_period_elapsed()` takes the substream pointer as 208962306a36Sopenharmony_ciits argument. Thus, you need to keep the substream pointer accessible 209062306a36Sopenharmony_cifrom the chip instance. For example, define ``substream`` field in the 209162306a36Sopenharmony_cichip record to hold the current running substream pointer, and set the 209262306a36Sopenharmony_cipointer value at ``open`` callback (and reset at ``close`` callback). 209362306a36Sopenharmony_ci 209462306a36Sopenharmony_ciIf you acquire a spinlock in the interrupt handler, and the lock is used 209562306a36Sopenharmony_ciin other PCM callbacks, too, then you have to release the lock before 209662306a36Sopenharmony_cicalling :c:func:`snd_pcm_period_elapsed()`, because 209762306a36Sopenharmony_ci:c:func:`snd_pcm_period_elapsed()` calls other PCM callbacks 209862306a36Sopenharmony_ciinside. 209962306a36Sopenharmony_ci 210062306a36Sopenharmony_ciTypical code would look like:: 210162306a36Sopenharmony_ci 210262306a36Sopenharmony_ci 210362306a36Sopenharmony_ci static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id) 210462306a36Sopenharmony_ci { 210562306a36Sopenharmony_ci struct mychip *chip = dev_id; 210662306a36Sopenharmony_ci spin_lock(&chip->lock); 210762306a36Sopenharmony_ci .... 210862306a36Sopenharmony_ci if (pcm_irq_invoked(chip)) { 210962306a36Sopenharmony_ci /* call updater, unlock before it */ 211062306a36Sopenharmony_ci spin_unlock(&chip->lock); 211162306a36Sopenharmony_ci snd_pcm_period_elapsed(chip->substream); 211262306a36Sopenharmony_ci spin_lock(&chip->lock); 211362306a36Sopenharmony_ci /* acknowledge the interrupt if necessary */ 211462306a36Sopenharmony_ci } 211562306a36Sopenharmony_ci .... 211662306a36Sopenharmony_ci spin_unlock(&chip->lock); 211762306a36Sopenharmony_ci return IRQ_HANDLED; 211862306a36Sopenharmony_ci } 211962306a36Sopenharmony_ci 212062306a36Sopenharmony_ciAlso, when the device can detect a buffer underrun/overrun, the driver 212162306a36Sopenharmony_cican notify the XRUN status to the PCM core by calling 212262306a36Sopenharmony_ci:c:func:`snd_pcm_stop_xrun()`. This function stops the stream and sets 212362306a36Sopenharmony_cithe PCM state to ``SNDRV_PCM_STATE_XRUN``. Note that it must be called 212462306a36Sopenharmony_cioutside the PCM stream lock, hence it can't be called from the atomic 212562306a36Sopenharmony_cicallback. 212662306a36Sopenharmony_ci 212762306a36Sopenharmony_ci 212862306a36Sopenharmony_ciHigh frequency timer interrupts 212962306a36Sopenharmony_ci~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 213062306a36Sopenharmony_ci 213162306a36Sopenharmony_ciThis happens when the hardware doesn't generate interrupts at the period 213262306a36Sopenharmony_ciboundary but issues timer interrupts at a fixed timer rate (e.g. es1968 213362306a36Sopenharmony_cior ymfpci drivers). In this case, you need to check the current hardware 213462306a36Sopenharmony_ciposition and accumulate the processed sample length at each interrupt. 213562306a36Sopenharmony_ciWhen the accumulated size exceeds the period size, call 213662306a36Sopenharmony_ci:c:func:`snd_pcm_period_elapsed()` and reset the accumulator. 213762306a36Sopenharmony_ci 213862306a36Sopenharmony_ciTypical code would look as follows:: 213962306a36Sopenharmony_ci 214062306a36Sopenharmony_ci 214162306a36Sopenharmony_ci static irqreturn_t snd_mychip_interrupt(int irq, void *dev_id) 214262306a36Sopenharmony_ci { 214362306a36Sopenharmony_ci struct mychip *chip = dev_id; 214462306a36Sopenharmony_ci spin_lock(&chip->lock); 214562306a36Sopenharmony_ci .... 214662306a36Sopenharmony_ci if (pcm_irq_invoked(chip)) { 214762306a36Sopenharmony_ci unsigned int last_ptr, size; 214862306a36Sopenharmony_ci /* get the current hardware pointer (in frames) */ 214962306a36Sopenharmony_ci last_ptr = get_hw_ptr(chip); 215062306a36Sopenharmony_ci /* calculate the processed frames since the 215162306a36Sopenharmony_ci * last update 215262306a36Sopenharmony_ci */ 215362306a36Sopenharmony_ci if (last_ptr < chip->last_ptr) 215462306a36Sopenharmony_ci size = runtime->buffer_size + last_ptr 215562306a36Sopenharmony_ci - chip->last_ptr; 215662306a36Sopenharmony_ci else 215762306a36Sopenharmony_ci size = last_ptr - chip->last_ptr; 215862306a36Sopenharmony_ci /* remember the last updated point */ 215962306a36Sopenharmony_ci chip->last_ptr = last_ptr; 216062306a36Sopenharmony_ci /* accumulate the size */ 216162306a36Sopenharmony_ci chip->size += size; 216262306a36Sopenharmony_ci /* over the period boundary? */ 216362306a36Sopenharmony_ci if (chip->size >= runtime->period_size) { 216462306a36Sopenharmony_ci /* reset the accumulator */ 216562306a36Sopenharmony_ci chip->size %= runtime->period_size; 216662306a36Sopenharmony_ci /* call updater */ 216762306a36Sopenharmony_ci spin_unlock(&chip->lock); 216862306a36Sopenharmony_ci snd_pcm_period_elapsed(substream); 216962306a36Sopenharmony_ci spin_lock(&chip->lock); 217062306a36Sopenharmony_ci } 217162306a36Sopenharmony_ci /* acknowledge the interrupt if necessary */ 217262306a36Sopenharmony_ci } 217362306a36Sopenharmony_ci .... 217462306a36Sopenharmony_ci spin_unlock(&chip->lock); 217562306a36Sopenharmony_ci return IRQ_HANDLED; 217662306a36Sopenharmony_ci } 217762306a36Sopenharmony_ci 217862306a36Sopenharmony_ci 217962306a36Sopenharmony_ci 218062306a36Sopenharmony_ciOn calling :c:func:`snd_pcm_period_elapsed()` 218162306a36Sopenharmony_ci~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 218262306a36Sopenharmony_ci 218362306a36Sopenharmony_ciIn both cases, even if more than one period has elapsed, you don't have 218462306a36Sopenharmony_cito call :c:func:`snd_pcm_period_elapsed()` many times. Call only 218562306a36Sopenharmony_cionce. And the PCM layer will check the current hardware pointer and 218662306a36Sopenharmony_ciupdate to the latest status. 218762306a36Sopenharmony_ci 218862306a36Sopenharmony_ciAtomicity 218962306a36Sopenharmony_ci--------- 219062306a36Sopenharmony_ci 219162306a36Sopenharmony_ciOne of the most important (and thus difficult to debug) problems in 219262306a36Sopenharmony_cikernel programming are race conditions. In the Linux kernel, they are 219362306a36Sopenharmony_ciusually avoided via spin-locks, mutexes or semaphores. In general, if a 219462306a36Sopenharmony_cirace condition can happen in an interrupt handler, it has to be managed 219562306a36Sopenharmony_ciatomically, and you have to use a spinlock to protect the critical 219662306a36Sopenharmony_cisection. If the critical section is not in interrupt handler code and if 219762306a36Sopenharmony_citaking a relatively long time to execute is acceptable, you should use 219862306a36Sopenharmony_cimutexes or semaphores instead. 219962306a36Sopenharmony_ci 220062306a36Sopenharmony_ciAs already seen, some PCM callbacks are atomic and some are not. For 220162306a36Sopenharmony_ciexample, the ``hw_params`` callback is non-atomic, while the ``trigger`` 220262306a36Sopenharmony_cicallback is atomic. This means, the latter is called already in a 220362306a36Sopenharmony_cispinlock held by the PCM middle layer, the PCM stream lock. Please 220462306a36Sopenharmony_citake this atomicity into account when you choose a locking scheme in 220562306a36Sopenharmony_cithe callbacks. 220662306a36Sopenharmony_ci 220762306a36Sopenharmony_ciIn the atomic callbacks, you cannot use functions which may call 220862306a36Sopenharmony_ci:c:func:`schedule()` or go to :c:func:`sleep()`. Semaphores and 220962306a36Sopenharmony_cimutexes can sleep, and hence they cannot be used inside the atomic 221062306a36Sopenharmony_cicallbacks (e.g. ``trigger`` callback). To implement some delay in such a 221162306a36Sopenharmony_cicallback, please use :c:func:`udelay()` or :c:func:`mdelay()`. 221262306a36Sopenharmony_ci 221362306a36Sopenharmony_ciAll three atomic callbacks (trigger, pointer, and ack) are called with 221462306a36Sopenharmony_cilocal interrupts disabled. 221562306a36Sopenharmony_ci 221662306a36Sopenharmony_ciHowever, it is possible to request all PCM operations to be non-atomic. 221762306a36Sopenharmony_ciThis assumes that all call sites are in 221862306a36Sopenharmony_cinon-atomic contexts. For example, the function 221962306a36Sopenharmony_ci:c:func:`snd_pcm_period_elapsed()` is called typically from the 222062306a36Sopenharmony_ciinterrupt handler. But, if you set up the driver to use a threaded 222162306a36Sopenharmony_ciinterrupt handler, this call can be in non-atomic context, too. In such 222262306a36Sopenharmony_cia case, you can set the ``nonatomic`` field of the struct snd_pcm object 222362306a36Sopenharmony_ciafter creating it. When this flag is set, mutex and rwsem are used internally 222462306a36Sopenharmony_ciin the PCM core instead of spin and rwlocks, so that you can call all PCM 222562306a36Sopenharmony_cifunctions safely in a non-atomic 222662306a36Sopenharmony_cicontext. 222762306a36Sopenharmony_ci 222862306a36Sopenharmony_ciAlso, in some cases, you might need to call 222962306a36Sopenharmony_ci:c:func:`snd_pcm_period_elapsed()` in the atomic context (e.g. the 223062306a36Sopenharmony_ciperiod gets elapsed during ``ack`` or other callback). There is a 223162306a36Sopenharmony_civariant that can be called inside the PCM stream lock 223262306a36Sopenharmony_ci:c:func:`snd_pcm_period_elapsed_under_stream_lock()` for that purpose, 223362306a36Sopenharmony_citoo. 223462306a36Sopenharmony_ci 223562306a36Sopenharmony_ciConstraints 223662306a36Sopenharmony_ci----------- 223762306a36Sopenharmony_ci 223862306a36Sopenharmony_ciDue to physical limitations, hardware is not infinitely configurable. 223962306a36Sopenharmony_ciThese limitations are expressed by setting constraints. 224062306a36Sopenharmony_ci 224162306a36Sopenharmony_ciFor example, in order to restrict the sample rates to some supported 224262306a36Sopenharmony_civalues, use :c:func:`snd_pcm_hw_constraint_list()`. You need to 224362306a36Sopenharmony_cicall this function in the open callback:: 224462306a36Sopenharmony_ci 224562306a36Sopenharmony_ci static unsigned int rates[] = 224662306a36Sopenharmony_ci {4000, 10000, 22050, 44100}; 224762306a36Sopenharmony_ci static struct snd_pcm_hw_constraint_list constraints_rates = { 224862306a36Sopenharmony_ci .count = ARRAY_SIZE(rates), 224962306a36Sopenharmony_ci .list = rates, 225062306a36Sopenharmony_ci .mask = 0, 225162306a36Sopenharmony_ci }; 225262306a36Sopenharmony_ci 225362306a36Sopenharmony_ci static int snd_mychip_pcm_open(struct snd_pcm_substream *substream) 225462306a36Sopenharmony_ci { 225562306a36Sopenharmony_ci int err; 225662306a36Sopenharmony_ci .... 225762306a36Sopenharmony_ci err = snd_pcm_hw_constraint_list(substream->runtime, 0, 225862306a36Sopenharmony_ci SNDRV_PCM_HW_PARAM_RATE, 225962306a36Sopenharmony_ci &constraints_rates); 226062306a36Sopenharmony_ci if (err < 0) 226162306a36Sopenharmony_ci return err; 226262306a36Sopenharmony_ci .... 226362306a36Sopenharmony_ci } 226462306a36Sopenharmony_ci 226562306a36Sopenharmony_ciThere are many different constraints. Look at ``sound/pcm.h`` for a 226662306a36Sopenharmony_cicomplete list. You can even define your own constraint rules. For 226762306a36Sopenharmony_ciexample, let's suppose my_chip can manage a substream of 1 channel if 226862306a36Sopenharmony_ciand only if the format is ``S16_LE``, otherwise it supports any format 226962306a36Sopenharmony_cispecified in struct snd_pcm_hardware (or in any other 227062306a36Sopenharmony_ciconstraint_list). You can build a rule like this:: 227162306a36Sopenharmony_ci 227262306a36Sopenharmony_ci static int hw_rule_channels_by_format(struct snd_pcm_hw_params *params, 227362306a36Sopenharmony_ci struct snd_pcm_hw_rule *rule) 227462306a36Sopenharmony_ci { 227562306a36Sopenharmony_ci struct snd_interval *c = hw_param_interval(params, 227662306a36Sopenharmony_ci SNDRV_PCM_HW_PARAM_CHANNELS); 227762306a36Sopenharmony_ci struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT); 227862306a36Sopenharmony_ci struct snd_interval ch; 227962306a36Sopenharmony_ci 228062306a36Sopenharmony_ci snd_interval_any(&ch); 228162306a36Sopenharmony_ci if (f->bits[0] == SNDRV_PCM_FMTBIT_S16_LE) { 228262306a36Sopenharmony_ci ch.min = ch.max = 1; 228362306a36Sopenharmony_ci ch.integer = 1; 228462306a36Sopenharmony_ci return snd_interval_refine(c, &ch); 228562306a36Sopenharmony_ci } 228662306a36Sopenharmony_ci return 0; 228762306a36Sopenharmony_ci } 228862306a36Sopenharmony_ci 228962306a36Sopenharmony_ci 229062306a36Sopenharmony_ciThen you need to call this function to add your rule:: 229162306a36Sopenharmony_ci 229262306a36Sopenharmony_ci snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_CHANNELS, 229362306a36Sopenharmony_ci hw_rule_channels_by_format, NULL, 229462306a36Sopenharmony_ci SNDRV_PCM_HW_PARAM_FORMAT, -1); 229562306a36Sopenharmony_ci 229662306a36Sopenharmony_ciThe rule function is called when an application sets the PCM format, and 229762306a36Sopenharmony_ciit refines the number of channels accordingly. But an application may 229862306a36Sopenharmony_ciset the number of channels before setting the format. Thus you also need 229962306a36Sopenharmony_cito define the inverse rule:: 230062306a36Sopenharmony_ci 230162306a36Sopenharmony_ci static int hw_rule_format_by_channels(struct snd_pcm_hw_params *params, 230262306a36Sopenharmony_ci struct snd_pcm_hw_rule *rule) 230362306a36Sopenharmony_ci { 230462306a36Sopenharmony_ci struct snd_interval *c = hw_param_interval(params, 230562306a36Sopenharmony_ci SNDRV_PCM_HW_PARAM_CHANNELS); 230662306a36Sopenharmony_ci struct snd_mask *f = hw_param_mask(params, SNDRV_PCM_HW_PARAM_FORMAT); 230762306a36Sopenharmony_ci struct snd_mask fmt; 230862306a36Sopenharmony_ci 230962306a36Sopenharmony_ci snd_mask_any(&fmt); /* Init the struct */ 231062306a36Sopenharmony_ci if (c->min < 2) { 231162306a36Sopenharmony_ci fmt.bits[0] &= SNDRV_PCM_FMTBIT_S16_LE; 231262306a36Sopenharmony_ci return snd_mask_refine(f, &fmt); 231362306a36Sopenharmony_ci } 231462306a36Sopenharmony_ci return 0; 231562306a36Sopenharmony_ci } 231662306a36Sopenharmony_ci 231762306a36Sopenharmony_ci 231862306a36Sopenharmony_ci... and in the open callback:: 231962306a36Sopenharmony_ci 232062306a36Sopenharmony_ci snd_pcm_hw_rule_add(substream->runtime, 0, SNDRV_PCM_HW_PARAM_FORMAT, 232162306a36Sopenharmony_ci hw_rule_format_by_channels, NULL, 232262306a36Sopenharmony_ci SNDRV_PCM_HW_PARAM_CHANNELS, -1); 232362306a36Sopenharmony_ci 232462306a36Sopenharmony_ciOne typical usage of the hw constraints is to align the buffer size 232562306a36Sopenharmony_ciwith the period size. By default, ALSA PCM core doesn't enforce the 232662306a36Sopenharmony_cibuffer size to be aligned with the period size. For example, it'd be 232762306a36Sopenharmony_cipossible to have a combination like 256 period bytes with 999 buffer 232862306a36Sopenharmony_cibytes. 232962306a36Sopenharmony_ci 233062306a36Sopenharmony_ciMany device chips, however, require the buffer to be a multiple of 233162306a36Sopenharmony_ciperiods. In such a case, call 233262306a36Sopenharmony_ci:c:func:`snd_pcm_hw_constraint_integer()` for 233362306a36Sopenharmony_ci``SNDRV_PCM_HW_PARAM_PERIODS``:: 233462306a36Sopenharmony_ci 233562306a36Sopenharmony_ci snd_pcm_hw_constraint_integer(substream->runtime, 233662306a36Sopenharmony_ci SNDRV_PCM_HW_PARAM_PERIODS); 233762306a36Sopenharmony_ci 233862306a36Sopenharmony_ciThis assures that the number of periods is integer, hence the buffer 233962306a36Sopenharmony_cisize is aligned with the period size. 234062306a36Sopenharmony_ci 234162306a36Sopenharmony_ciThe hw constraint is a very powerful mechanism to define the 234262306a36Sopenharmony_cipreferred PCM configuration, and there are relevant helpers. 234362306a36Sopenharmony_ciI won't give more details here, rather I would like to say, “Luke, use 234462306a36Sopenharmony_cithe source.” 234562306a36Sopenharmony_ci 234662306a36Sopenharmony_ciControl Interface 234762306a36Sopenharmony_ci================= 234862306a36Sopenharmony_ci 234962306a36Sopenharmony_ciGeneral 235062306a36Sopenharmony_ci------- 235162306a36Sopenharmony_ci 235262306a36Sopenharmony_ciThe control interface is used widely for many switches, sliders, etc. 235362306a36Sopenharmony_ciwhich are accessed from user-space. Its most important use is the mixer 235462306a36Sopenharmony_ciinterface. In other words, since ALSA 0.9.x, all the mixer stuff is 235562306a36Sopenharmony_ciimplemented on the control kernel API. 235662306a36Sopenharmony_ci 235762306a36Sopenharmony_ciALSA has a well-defined AC97 control module. If your chip supports only 235862306a36Sopenharmony_cithe AC97 and nothing else, you can skip this section. 235962306a36Sopenharmony_ci 236062306a36Sopenharmony_ciThe control API is defined in ``<sound/control.h>``. Include this file 236162306a36Sopenharmony_ciif you want to add your own controls. 236262306a36Sopenharmony_ci 236362306a36Sopenharmony_ciDefinition of Controls 236462306a36Sopenharmony_ci---------------------- 236562306a36Sopenharmony_ci 236662306a36Sopenharmony_ciTo create a new control, you need to define the following three 236762306a36Sopenharmony_cicallbacks: ``info``, ``get`` and ``put``. Then, define a 236862306a36Sopenharmony_cistruct snd_kcontrol_new record, such as:: 236962306a36Sopenharmony_ci 237062306a36Sopenharmony_ci 237162306a36Sopenharmony_ci static struct snd_kcontrol_new my_control = { 237262306a36Sopenharmony_ci .iface = SNDRV_CTL_ELEM_IFACE_MIXER, 237362306a36Sopenharmony_ci .name = "PCM Playback Switch", 237462306a36Sopenharmony_ci .index = 0, 237562306a36Sopenharmony_ci .access = SNDRV_CTL_ELEM_ACCESS_READWRITE, 237662306a36Sopenharmony_ci .private_value = 0xffff, 237762306a36Sopenharmony_ci .info = my_control_info, 237862306a36Sopenharmony_ci .get = my_control_get, 237962306a36Sopenharmony_ci .put = my_control_put 238062306a36Sopenharmony_ci }; 238162306a36Sopenharmony_ci 238262306a36Sopenharmony_ci 238362306a36Sopenharmony_ciThe ``iface`` field specifies the control type, 238462306a36Sopenharmony_ci``SNDRV_CTL_ELEM_IFACE_XXX``, which is usually ``MIXER``. Use ``CARD`` 238562306a36Sopenharmony_cifor global controls that are not logically part of the mixer. If the 238662306a36Sopenharmony_cicontrol is closely associated with some specific device on the sound 238762306a36Sopenharmony_cicard, use ``HWDEP``, ``PCM``, ``RAWMIDI``, ``TIMER``, or ``SEQUENCER``, 238862306a36Sopenharmony_ciand specify the device number with the ``device`` and ``subdevice`` 238962306a36Sopenharmony_cifields. 239062306a36Sopenharmony_ci 239162306a36Sopenharmony_ciThe ``name`` is the name identifier string. Since ALSA 0.9.x, the 239262306a36Sopenharmony_cicontrol name is very important, because its role is classified from 239362306a36Sopenharmony_ciits name. There are pre-defined standard control names. The details 239462306a36Sopenharmony_ciare described in the `Control Names`_ subsection. 239562306a36Sopenharmony_ci 239662306a36Sopenharmony_ciThe ``index`` field holds the index number of this control. If there 239762306a36Sopenharmony_ciare several different controls with the same name, they can be 239862306a36Sopenharmony_cidistinguished by the index number. This is the case when several 239962306a36Sopenharmony_cicodecs exist on the card. If the index is zero, you can omit the 240062306a36Sopenharmony_cidefinition above. 240162306a36Sopenharmony_ci 240262306a36Sopenharmony_ciThe ``access`` field contains the access type of this control. Give 240362306a36Sopenharmony_cithe combination of bit masks, ``SNDRV_CTL_ELEM_ACCESS_XXX``, 240462306a36Sopenharmony_cithere. The details will be explained in the `Access Flags`_ 240562306a36Sopenharmony_cisubsection. 240662306a36Sopenharmony_ci 240762306a36Sopenharmony_ciThe ``private_value`` field contains an arbitrary long integer value 240862306a36Sopenharmony_cifor this record. When using the generic ``info``, ``get`` and ``put`` 240962306a36Sopenharmony_cicallbacks, you can pass a value through this field. If several small 241062306a36Sopenharmony_cinumbers are necessary, you can combine them in bitwise. Or, it's 241162306a36Sopenharmony_cipossible to store a pointer (casted to unsigned long) of some record in 241262306a36Sopenharmony_cithis field, too. 241362306a36Sopenharmony_ci 241462306a36Sopenharmony_ciThe ``tlv`` field can be used to provide metadata about the control; 241562306a36Sopenharmony_cisee the `Metadata`_ subsection. 241662306a36Sopenharmony_ci 241762306a36Sopenharmony_ciThe other three are `Control Callbacks`_. 241862306a36Sopenharmony_ci 241962306a36Sopenharmony_ciControl Names 242062306a36Sopenharmony_ci------------- 242162306a36Sopenharmony_ci 242262306a36Sopenharmony_ciThere are some standards to define the control names. A control is 242362306a36Sopenharmony_ciusually defined from the three parts as “SOURCE DIRECTION FUNCTION”. 242462306a36Sopenharmony_ci 242562306a36Sopenharmony_ciThe first, ``SOURCE``, specifies the source of the control, and is a 242662306a36Sopenharmony_cistring such as “Master”, “PCM”, “CD” and “Line”. There are many 242762306a36Sopenharmony_cipre-defined sources. 242862306a36Sopenharmony_ci 242962306a36Sopenharmony_ciThe second, ``DIRECTION``, is one of the following strings according to 243062306a36Sopenharmony_cithe direction of the control: “Playback”, “Capture”, “Bypass Playback” 243162306a36Sopenharmony_ciand “Bypass Capture”. Or, it can be omitted, meaning both playback and 243262306a36Sopenharmony_cicapture directions. 243362306a36Sopenharmony_ci 243462306a36Sopenharmony_ciThe third, ``FUNCTION``, is one of the following strings according to 243562306a36Sopenharmony_cithe function of the control: “Switch”, “Volume” and “Route”. 243662306a36Sopenharmony_ci 243762306a36Sopenharmony_ciThe example of control names are, thus, “Master Capture Switch” or “PCM 243862306a36Sopenharmony_ciPlayback Volume”. 243962306a36Sopenharmony_ci 244062306a36Sopenharmony_ciThere are some exceptions: 244162306a36Sopenharmony_ci 244262306a36Sopenharmony_ciGlobal capture and playback 244362306a36Sopenharmony_ci~~~~~~~~~~~~~~~~~~~~~~~~~~~ 244462306a36Sopenharmony_ci 244562306a36Sopenharmony_ci“Capture Source”, “Capture Switch” and “Capture Volume” are used for the 244662306a36Sopenharmony_ciglobal capture (input) source, switch and volume. Similarly, “Playback 244762306a36Sopenharmony_ciSwitch” and “Playback Volume” are used for the global output gain switch 244862306a36Sopenharmony_ciand volume. 244962306a36Sopenharmony_ci 245062306a36Sopenharmony_ciTone-controls 245162306a36Sopenharmony_ci~~~~~~~~~~~~~ 245262306a36Sopenharmony_ci 245362306a36Sopenharmony_citone-control switch and volumes are specified like “Tone Control - XXX”, 245462306a36Sopenharmony_cie.g. “Tone Control - Switch”, “Tone Control - Bass”, “Tone Control - 245562306a36Sopenharmony_ciCenter”. 245662306a36Sopenharmony_ci 245762306a36Sopenharmony_ci3D controls 245862306a36Sopenharmony_ci~~~~~~~~~~~ 245962306a36Sopenharmony_ci 246062306a36Sopenharmony_ci3D-control switches and volumes are specified like “3D Control - XXX”, 246162306a36Sopenharmony_cie.g. “3D Control - Switch”, “3D Control - Center”, “3D Control - Space”. 246262306a36Sopenharmony_ci 246362306a36Sopenharmony_ciMic boost 246462306a36Sopenharmony_ci~~~~~~~~~ 246562306a36Sopenharmony_ci 246662306a36Sopenharmony_ciMic-boost switch is set as “Mic Boost” or “Mic Boost (6dB)”. 246762306a36Sopenharmony_ci 246862306a36Sopenharmony_ciMore precise information can be found in 246962306a36Sopenharmony_ci``Documentation/sound/designs/control-names.rst``. 247062306a36Sopenharmony_ci 247162306a36Sopenharmony_ciAccess Flags 247262306a36Sopenharmony_ci------------ 247362306a36Sopenharmony_ci 247462306a36Sopenharmony_ciThe access flag is the bitmask which specifies the access type of the 247562306a36Sopenharmony_cigiven control. The default access type is 247662306a36Sopenharmony_ci``SNDRV_CTL_ELEM_ACCESS_READWRITE``, which means both read and write are 247762306a36Sopenharmony_ciallowed to this control. When the access flag is omitted (i.e. = 0), it 247862306a36Sopenharmony_ciis considered as ``READWRITE`` access by default. 247962306a36Sopenharmony_ci 248062306a36Sopenharmony_ciWhen the control is read-only, pass ``SNDRV_CTL_ELEM_ACCESS_READ`` 248162306a36Sopenharmony_ciinstead. In this case, you don't have to define the ``put`` callback. 248262306a36Sopenharmony_ciSimilarly, when the control is write-only (although it's a rare case), 248362306a36Sopenharmony_ciyou can use the ``WRITE`` flag instead, and you don't need the ``get`` 248462306a36Sopenharmony_cicallback. 248562306a36Sopenharmony_ci 248662306a36Sopenharmony_ciIf the control value changes frequently (e.g. the VU meter), 248762306a36Sopenharmony_ci``VOLATILE`` flag should be given. This means that the control may be 248862306a36Sopenharmony_cichanged without `Change notification`_. Applications should poll such 248962306a36Sopenharmony_cia control constantly. 249062306a36Sopenharmony_ci 249162306a36Sopenharmony_ciWhen the control may be updated, but currently has no effect on anything, 249262306a36Sopenharmony_cisetting the ``INACTIVE`` flag may be appropriate. For example, PCM 249362306a36Sopenharmony_cicontrols should be inactive while no PCM device is open. 249462306a36Sopenharmony_ci 249562306a36Sopenharmony_ciThere are ``LOCK`` and ``OWNER`` flags to change the write permissions. 249662306a36Sopenharmony_ci 249762306a36Sopenharmony_ciControl Callbacks 249862306a36Sopenharmony_ci----------------- 249962306a36Sopenharmony_ci 250062306a36Sopenharmony_ciinfo callback 250162306a36Sopenharmony_ci~~~~~~~~~~~~~ 250262306a36Sopenharmony_ci 250362306a36Sopenharmony_ciThe ``info`` callback is used to get detailed information on this 250462306a36Sopenharmony_cicontrol. This must store the values of the given 250562306a36Sopenharmony_cistruct snd_ctl_elem_info object. For example, 250662306a36Sopenharmony_cifor a boolean control with a single element:: 250762306a36Sopenharmony_ci 250862306a36Sopenharmony_ci 250962306a36Sopenharmony_ci static int snd_myctl_mono_info(struct snd_kcontrol *kcontrol, 251062306a36Sopenharmony_ci struct snd_ctl_elem_info *uinfo) 251162306a36Sopenharmony_ci { 251262306a36Sopenharmony_ci uinfo->type = SNDRV_CTL_ELEM_TYPE_BOOLEAN; 251362306a36Sopenharmony_ci uinfo->count = 1; 251462306a36Sopenharmony_ci uinfo->value.integer.min = 0; 251562306a36Sopenharmony_ci uinfo->value.integer.max = 1; 251662306a36Sopenharmony_ci return 0; 251762306a36Sopenharmony_ci } 251862306a36Sopenharmony_ci 251962306a36Sopenharmony_ci 252062306a36Sopenharmony_ci 252162306a36Sopenharmony_ciThe ``type`` field specifies the type of the control. There are 252262306a36Sopenharmony_ci``BOOLEAN``, ``INTEGER``, ``ENUMERATED``, ``BYTES``, ``IEC958`` and 252362306a36Sopenharmony_ci``INTEGER64``. The ``count`` field specifies the number of elements in 252462306a36Sopenharmony_cithis control. For example, a stereo volume would have count = 2. The 252562306a36Sopenharmony_ci``value`` field is a union, and the values stored depend on the 252662306a36Sopenharmony_citype. The boolean and integer types are identical. 252762306a36Sopenharmony_ci 252862306a36Sopenharmony_ciThe enumerated type is a bit different from the others. You'll need to 252962306a36Sopenharmony_ciset the string for the selectec item index:: 253062306a36Sopenharmony_ci 253162306a36Sopenharmony_ci static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol, 253262306a36Sopenharmony_ci struct snd_ctl_elem_info *uinfo) 253362306a36Sopenharmony_ci { 253462306a36Sopenharmony_ci static char *texts[4] = { 253562306a36Sopenharmony_ci "First", "Second", "Third", "Fourth" 253662306a36Sopenharmony_ci }; 253762306a36Sopenharmony_ci uinfo->type = SNDRV_CTL_ELEM_TYPE_ENUMERATED; 253862306a36Sopenharmony_ci uinfo->count = 1; 253962306a36Sopenharmony_ci uinfo->value.enumerated.items = 4; 254062306a36Sopenharmony_ci if (uinfo->value.enumerated.item > 3) 254162306a36Sopenharmony_ci uinfo->value.enumerated.item = 3; 254262306a36Sopenharmony_ci strcpy(uinfo->value.enumerated.name, 254362306a36Sopenharmony_ci texts[uinfo->value.enumerated.item]); 254462306a36Sopenharmony_ci return 0; 254562306a36Sopenharmony_ci } 254662306a36Sopenharmony_ci 254762306a36Sopenharmony_ciThe above callback can be simplified with a helper function, 254862306a36Sopenharmony_ci:c:func:`snd_ctl_enum_info()`. The final code looks like below. 254962306a36Sopenharmony_ci(You can pass ``ARRAY_SIZE(texts)`` instead of 4 in the third argument; 255062306a36Sopenharmony_ciit's a matter of taste.) 255162306a36Sopenharmony_ci 255262306a36Sopenharmony_ci:: 255362306a36Sopenharmony_ci 255462306a36Sopenharmony_ci static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol, 255562306a36Sopenharmony_ci struct snd_ctl_elem_info *uinfo) 255662306a36Sopenharmony_ci { 255762306a36Sopenharmony_ci static char *texts[4] = { 255862306a36Sopenharmony_ci "First", "Second", "Third", "Fourth" 255962306a36Sopenharmony_ci }; 256062306a36Sopenharmony_ci return snd_ctl_enum_info(uinfo, 1, 4, texts); 256162306a36Sopenharmony_ci } 256262306a36Sopenharmony_ci 256362306a36Sopenharmony_ci 256462306a36Sopenharmony_ciSome common info callbacks are available for your convenience: 256562306a36Sopenharmony_ci:c:func:`snd_ctl_boolean_mono_info()` and 256662306a36Sopenharmony_ci:c:func:`snd_ctl_boolean_stereo_info()`. Obviously, the former 256762306a36Sopenharmony_ciis an info callback for a mono channel boolean item, just like 256862306a36Sopenharmony_ci:c:func:`snd_myctl_mono_info()` above, and the latter is for a 256962306a36Sopenharmony_cistereo channel boolean item. 257062306a36Sopenharmony_ci 257162306a36Sopenharmony_ciget callback 257262306a36Sopenharmony_ci~~~~~~~~~~~~ 257362306a36Sopenharmony_ci 257462306a36Sopenharmony_ciThis callback is used to read the current value of the control, so it 257562306a36Sopenharmony_cican be returned to user-space. 257662306a36Sopenharmony_ci 257762306a36Sopenharmony_ciFor example:: 257862306a36Sopenharmony_ci 257962306a36Sopenharmony_ci static int snd_myctl_get(struct snd_kcontrol *kcontrol, 258062306a36Sopenharmony_ci struct snd_ctl_elem_value *ucontrol) 258162306a36Sopenharmony_ci { 258262306a36Sopenharmony_ci struct mychip *chip = snd_kcontrol_chip(kcontrol); 258362306a36Sopenharmony_ci ucontrol->value.integer.value[0] = get_some_value(chip); 258462306a36Sopenharmony_ci return 0; 258562306a36Sopenharmony_ci } 258662306a36Sopenharmony_ci 258762306a36Sopenharmony_ci 258862306a36Sopenharmony_ci 258962306a36Sopenharmony_ciThe ``value`` field depends on the type of control as well as on the 259062306a36Sopenharmony_ciinfo callback. For example, the sb driver uses this field to store the 259162306a36Sopenharmony_ciregister offset, the bit-shift and the bit-mask. The ``private_value`` 259262306a36Sopenharmony_cifield is set as follows:: 259362306a36Sopenharmony_ci 259462306a36Sopenharmony_ci .private_value = reg | (shift << 16) | (mask << 24) 259562306a36Sopenharmony_ci 259662306a36Sopenharmony_ciand is retrieved in callbacks like:: 259762306a36Sopenharmony_ci 259862306a36Sopenharmony_ci static int snd_sbmixer_get_single(struct snd_kcontrol *kcontrol, 259962306a36Sopenharmony_ci struct snd_ctl_elem_value *ucontrol) 260062306a36Sopenharmony_ci { 260162306a36Sopenharmony_ci int reg = kcontrol->private_value & 0xff; 260262306a36Sopenharmony_ci int shift = (kcontrol->private_value >> 16) & 0xff; 260362306a36Sopenharmony_ci int mask = (kcontrol->private_value >> 24) & 0xff; 260462306a36Sopenharmony_ci .... 260562306a36Sopenharmony_ci } 260662306a36Sopenharmony_ci 260762306a36Sopenharmony_ciIn the ``get`` callback, you have to fill all the elements if the 260862306a36Sopenharmony_cicontrol has more than one element, i.e. ``count > 1``. In the example 260962306a36Sopenharmony_ciabove, we filled only one element (``value.integer.value[0]``) since 261062306a36Sopenharmony_ci``count = 1`` is assumed. 261162306a36Sopenharmony_ci 261262306a36Sopenharmony_ciput callback 261362306a36Sopenharmony_ci~~~~~~~~~~~~ 261462306a36Sopenharmony_ci 261562306a36Sopenharmony_ciThis callback is used to write a value coming from user-space. 261662306a36Sopenharmony_ci 261762306a36Sopenharmony_ciFor example:: 261862306a36Sopenharmony_ci 261962306a36Sopenharmony_ci static int snd_myctl_put(struct snd_kcontrol *kcontrol, 262062306a36Sopenharmony_ci struct snd_ctl_elem_value *ucontrol) 262162306a36Sopenharmony_ci { 262262306a36Sopenharmony_ci struct mychip *chip = snd_kcontrol_chip(kcontrol); 262362306a36Sopenharmony_ci int changed = 0; 262462306a36Sopenharmony_ci if (chip->current_value != 262562306a36Sopenharmony_ci ucontrol->value.integer.value[0]) { 262662306a36Sopenharmony_ci change_current_value(chip, 262762306a36Sopenharmony_ci ucontrol->value.integer.value[0]); 262862306a36Sopenharmony_ci changed = 1; 262962306a36Sopenharmony_ci } 263062306a36Sopenharmony_ci return changed; 263162306a36Sopenharmony_ci } 263262306a36Sopenharmony_ci 263362306a36Sopenharmony_ci 263462306a36Sopenharmony_ci 263562306a36Sopenharmony_ciAs seen above, you have to return 1 if the value is changed. If the 263662306a36Sopenharmony_civalue is not changed, return 0 instead. If any fatal error happens, 263762306a36Sopenharmony_cireturn a negative error code as usual. 263862306a36Sopenharmony_ci 263962306a36Sopenharmony_ciAs in the ``get`` callback, when the control has more than one 264062306a36Sopenharmony_cielement, all elements must be evaluated in this callback, too. 264162306a36Sopenharmony_ci 264262306a36Sopenharmony_ciCallbacks are not atomic 264362306a36Sopenharmony_ci~~~~~~~~~~~~~~~~~~~~~~~~ 264462306a36Sopenharmony_ci 264562306a36Sopenharmony_ciAll these three callbacks are not-atomic. 264662306a36Sopenharmony_ci 264762306a36Sopenharmony_ciControl Constructor 264862306a36Sopenharmony_ci------------------- 264962306a36Sopenharmony_ci 265062306a36Sopenharmony_ciWhen everything is ready, finally we can create a new control. To create 265162306a36Sopenharmony_cia control, there are two functions to be called, 265262306a36Sopenharmony_ci:c:func:`snd_ctl_new1()` and :c:func:`snd_ctl_add()`. 265362306a36Sopenharmony_ci 265462306a36Sopenharmony_ciIn the simplest way, you can do it like this:: 265562306a36Sopenharmony_ci 265662306a36Sopenharmony_ci err = snd_ctl_add(card, snd_ctl_new1(&my_control, chip)); 265762306a36Sopenharmony_ci if (err < 0) 265862306a36Sopenharmony_ci return err; 265962306a36Sopenharmony_ci 266062306a36Sopenharmony_ciwhere ``my_control`` is the struct snd_kcontrol_new object defined above, 266162306a36Sopenharmony_ciand chip is the object pointer to be passed to kcontrol->private_data which 266262306a36Sopenharmony_cican be referred to in callbacks. 266362306a36Sopenharmony_ci 266462306a36Sopenharmony_ci:c:func:`snd_ctl_new1()` allocates a new struct snd_kcontrol instance, and 266562306a36Sopenharmony_ci:c:func:`snd_ctl_add()` assigns the given control component to the 266662306a36Sopenharmony_cicard. 266762306a36Sopenharmony_ci 266862306a36Sopenharmony_ciChange Notification 266962306a36Sopenharmony_ci------------------- 267062306a36Sopenharmony_ci 267162306a36Sopenharmony_ciIf you need to change and update a control in the interrupt routine, you 267262306a36Sopenharmony_cican call :c:func:`snd_ctl_notify()`. For example:: 267362306a36Sopenharmony_ci 267462306a36Sopenharmony_ci snd_ctl_notify(card, SNDRV_CTL_EVENT_MASK_VALUE, id_pointer); 267562306a36Sopenharmony_ci 267662306a36Sopenharmony_ciThis function takes the card pointer, the event-mask, and the control id 267762306a36Sopenharmony_cipointer for the notification. The event-mask specifies the types of 267862306a36Sopenharmony_cinotification, for example, in the above example, the change of control 267962306a36Sopenharmony_civalues is notified. The id pointer is the pointer of struct snd_ctl_elem_id 268062306a36Sopenharmony_cito be notified. You can find some examples in ``es1938.c`` or ``es1968.c`` 268162306a36Sopenharmony_cifor hardware volume interrupts. 268262306a36Sopenharmony_ci 268362306a36Sopenharmony_ciMetadata 268462306a36Sopenharmony_ci-------- 268562306a36Sopenharmony_ci 268662306a36Sopenharmony_ciTo provide information about the dB values of a mixer control, use one of 268762306a36Sopenharmony_cithe ``DECLARE_TLV_xxx`` macros from ``<sound/tlv.h>`` to define a 268862306a36Sopenharmony_civariable containing this information, set the ``tlv.p`` field to point to 268962306a36Sopenharmony_cithis variable, and include the ``SNDRV_CTL_ELEM_ACCESS_TLV_READ`` flag 269062306a36Sopenharmony_ciin the ``access`` field; like this:: 269162306a36Sopenharmony_ci 269262306a36Sopenharmony_ci static DECLARE_TLV_DB_SCALE(db_scale_my_control, -4050, 150, 0); 269362306a36Sopenharmony_ci 269462306a36Sopenharmony_ci static struct snd_kcontrol_new my_control = { 269562306a36Sopenharmony_ci ... 269662306a36Sopenharmony_ci .access = SNDRV_CTL_ELEM_ACCESS_READWRITE | 269762306a36Sopenharmony_ci SNDRV_CTL_ELEM_ACCESS_TLV_READ, 269862306a36Sopenharmony_ci ... 269962306a36Sopenharmony_ci .tlv.p = db_scale_my_control, 270062306a36Sopenharmony_ci }; 270162306a36Sopenharmony_ci 270262306a36Sopenharmony_ci 270362306a36Sopenharmony_ciThe :c:func:`DECLARE_TLV_DB_SCALE()` macro defines information 270462306a36Sopenharmony_ciabout a mixer control where each step in the control's value changes the 270562306a36Sopenharmony_cidB value by a constant dB amount. The first parameter is the name of the 270662306a36Sopenharmony_civariable to be defined. The second parameter is the minimum value, in 270762306a36Sopenharmony_ciunits of 0.01 dB. The third parameter is the step size, in units of 0.01 270862306a36Sopenharmony_cidB. Set the fourth parameter to 1 if the minimum value actually mutes 270962306a36Sopenharmony_cithe control. 271062306a36Sopenharmony_ci 271162306a36Sopenharmony_ciThe :c:func:`DECLARE_TLV_DB_LINEAR()` macro defines information 271262306a36Sopenharmony_ciabout a mixer control where the control's value affects the output 271362306a36Sopenharmony_cilinearly. The first parameter is the name of the variable to be defined. 271462306a36Sopenharmony_ciThe second parameter is the minimum value, in units of 0.01 dB. The 271562306a36Sopenharmony_cithird parameter is the maximum value, in units of 0.01 dB. If the 271662306a36Sopenharmony_ciminimum value mutes the control, set the second parameter to 271762306a36Sopenharmony_ci``TLV_DB_GAIN_MUTE``. 271862306a36Sopenharmony_ci 271962306a36Sopenharmony_ciAPI for AC97 Codec 272062306a36Sopenharmony_ci================== 272162306a36Sopenharmony_ci 272262306a36Sopenharmony_ciGeneral 272362306a36Sopenharmony_ci------- 272462306a36Sopenharmony_ci 272562306a36Sopenharmony_ciThe ALSA AC97 codec layer is a well-defined one, and you don't have to 272662306a36Sopenharmony_ciwrite much code to control it. Only low-level control routines are 272762306a36Sopenharmony_cinecessary. The AC97 codec API is defined in ``<sound/ac97_codec.h>``. 272862306a36Sopenharmony_ci 272962306a36Sopenharmony_ciFull Code Example 273062306a36Sopenharmony_ci----------------- 273162306a36Sopenharmony_ci 273262306a36Sopenharmony_ci:: 273362306a36Sopenharmony_ci 273462306a36Sopenharmony_ci struct mychip { 273562306a36Sopenharmony_ci .... 273662306a36Sopenharmony_ci struct snd_ac97 *ac97; 273762306a36Sopenharmony_ci .... 273862306a36Sopenharmony_ci }; 273962306a36Sopenharmony_ci 274062306a36Sopenharmony_ci static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97, 274162306a36Sopenharmony_ci unsigned short reg) 274262306a36Sopenharmony_ci { 274362306a36Sopenharmony_ci struct mychip *chip = ac97->private_data; 274462306a36Sopenharmony_ci .... 274562306a36Sopenharmony_ci /* read a register value here from the codec */ 274662306a36Sopenharmony_ci return the_register_value; 274762306a36Sopenharmony_ci } 274862306a36Sopenharmony_ci 274962306a36Sopenharmony_ci static void snd_mychip_ac97_write(struct snd_ac97 *ac97, 275062306a36Sopenharmony_ci unsigned short reg, unsigned short val) 275162306a36Sopenharmony_ci { 275262306a36Sopenharmony_ci struct mychip *chip = ac97->private_data; 275362306a36Sopenharmony_ci .... 275462306a36Sopenharmony_ci /* write the given register value to the codec */ 275562306a36Sopenharmony_ci } 275662306a36Sopenharmony_ci 275762306a36Sopenharmony_ci static int snd_mychip_ac97(struct mychip *chip) 275862306a36Sopenharmony_ci { 275962306a36Sopenharmony_ci struct snd_ac97_bus *bus; 276062306a36Sopenharmony_ci struct snd_ac97_template ac97; 276162306a36Sopenharmony_ci int err; 276262306a36Sopenharmony_ci static struct snd_ac97_bus_ops ops = { 276362306a36Sopenharmony_ci .write = snd_mychip_ac97_write, 276462306a36Sopenharmony_ci .read = snd_mychip_ac97_read, 276562306a36Sopenharmony_ci }; 276662306a36Sopenharmony_ci 276762306a36Sopenharmony_ci err = snd_ac97_bus(chip->card, 0, &ops, NULL, &bus); 276862306a36Sopenharmony_ci if (err < 0) 276962306a36Sopenharmony_ci return err; 277062306a36Sopenharmony_ci memset(&ac97, 0, sizeof(ac97)); 277162306a36Sopenharmony_ci ac97.private_data = chip; 277262306a36Sopenharmony_ci return snd_ac97_mixer(bus, &ac97, &chip->ac97); 277362306a36Sopenharmony_ci } 277462306a36Sopenharmony_ci 277562306a36Sopenharmony_ci 277662306a36Sopenharmony_ciAC97 Constructor 277762306a36Sopenharmony_ci---------------- 277862306a36Sopenharmony_ci 277962306a36Sopenharmony_ciTo create an ac97 instance, first call :c:func:`snd_ac97_bus()` 278062306a36Sopenharmony_ciwith an ``ac97_bus_ops_t`` record with callback functions:: 278162306a36Sopenharmony_ci 278262306a36Sopenharmony_ci struct snd_ac97_bus *bus; 278362306a36Sopenharmony_ci static struct snd_ac97_bus_ops ops = { 278462306a36Sopenharmony_ci .write = snd_mychip_ac97_write, 278562306a36Sopenharmony_ci .read = snd_mychip_ac97_read, 278662306a36Sopenharmony_ci }; 278762306a36Sopenharmony_ci 278862306a36Sopenharmony_ci snd_ac97_bus(card, 0, &ops, NULL, &pbus); 278962306a36Sopenharmony_ci 279062306a36Sopenharmony_ciThe bus record is shared among all belonging ac97 instances. 279162306a36Sopenharmony_ci 279262306a36Sopenharmony_ciAnd then call :c:func:`snd_ac97_mixer()` with a struct snd_ac97_template 279362306a36Sopenharmony_cirecord together with the bus pointer created above:: 279462306a36Sopenharmony_ci 279562306a36Sopenharmony_ci struct snd_ac97_template ac97; 279662306a36Sopenharmony_ci int err; 279762306a36Sopenharmony_ci 279862306a36Sopenharmony_ci memset(&ac97, 0, sizeof(ac97)); 279962306a36Sopenharmony_ci ac97.private_data = chip; 280062306a36Sopenharmony_ci snd_ac97_mixer(bus, &ac97, &chip->ac97); 280162306a36Sopenharmony_ci 280262306a36Sopenharmony_ciwhere chip->ac97 is a pointer to a newly created ``ac97_t`` 280362306a36Sopenharmony_ciinstance. In this case, the chip pointer is set as the private data, 280462306a36Sopenharmony_ciso that the read/write callback functions can refer to this chip 280562306a36Sopenharmony_ciinstance. This instance is not necessarily stored in the chip 280662306a36Sopenharmony_cirecord. If you need to change the register values from the driver, or 280762306a36Sopenharmony_cineed the suspend/resume of ac97 codecs, keep this pointer to pass to 280862306a36Sopenharmony_cithe corresponding functions. 280962306a36Sopenharmony_ci 281062306a36Sopenharmony_ciAC97 Callbacks 281162306a36Sopenharmony_ci-------------- 281262306a36Sopenharmony_ci 281362306a36Sopenharmony_ciThe standard callbacks are ``read`` and ``write``. Obviously they 281462306a36Sopenharmony_cicorrespond to the functions for read and write accesses to the 281562306a36Sopenharmony_cihardware low-level codes. 281662306a36Sopenharmony_ci 281762306a36Sopenharmony_ciThe ``read`` callback returns the register value specified in the 281862306a36Sopenharmony_ciargument:: 281962306a36Sopenharmony_ci 282062306a36Sopenharmony_ci static unsigned short snd_mychip_ac97_read(struct snd_ac97 *ac97, 282162306a36Sopenharmony_ci unsigned short reg) 282262306a36Sopenharmony_ci { 282362306a36Sopenharmony_ci struct mychip *chip = ac97->private_data; 282462306a36Sopenharmony_ci .... 282562306a36Sopenharmony_ci return the_register_value; 282662306a36Sopenharmony_ci } 282762306a36Sopenharmony_ci 282862306a36Sopenharmony_ciHere, the chip can be cast from ``ac97->private_data``. 282962306a36Sopenharmony_ci 283062306a36Sopenharmony_ciMeanwhile, the ``write`` callback is used to set the register 283162306a36Sopenharmony_civalue:: 283262306a36Sopenharmony_ci 283362306a36Sopenharmony_ci static void snd_mychip_ac97_write(struct snd_ac97 *ac97, 283462306a36Sopenharmony_ci unsigned short reg, unsigned short val) 283562306a36Sopenharmony_ci 283662306a36Sopenharmony_ci 283762306a36Sopenharmony_ciThese callbacks are non-atomic like the control API callbacks. 283862306a36Sopenharmony_ci 283962306a36Sopenharmony_ciThere are also other callbacks: ``reset``, ``wait`` and ``init``. 284062306a36Sopenharmony_ci 284162306a36Sopenharmony_ciThe ``reset`` callback is used to reset the codec. If the chip 284262306a36Sopenharmony_cirequires a special kind of reset, you can define this callback. 284362306a36Sopenharmony_ci 284462306a36Sopenharmony_ciThe ``wait`` callback is used to add some waiting time in the standard 284562306a36Sopenharmony_ciinitialization of the codec. If the chip requires the extra waiting 284662306a36Sopenharmony_citime, define this callback. 284762306a36Sopenharmony_ci 284862306a36Sopenharmony_ciThe ``init`` callback is used for additional initialization of the 284962306a36Sopenharmony_cicodec. 285062306a36Sopenharmony_ci 285162306a36Sopenharmony_ciUpdating Registers in The Driver 285262306a36Sopenharmony_ci-------------------------------- 285362306a36Sopenharmony_ci 285462306a36Sopenharmony_ciIf you need to access to the codec from the driver, you can call the 285562306a36Sopenharmony_cifollowing functions: :c:func:`snd_ac97_write()`, 285662306a36Sopenharmony_ci:c:func:`snd_ac97_read()`, :c:func:`snd_ac97_update()` and 285762306a36Sopenharmony_ci:c:func:`snd_ac97_update_bits()`. 285862306a36Sopenharmony_ci 285962306a36Sopenharmony_ciBoth :c:func:`snd_ac97_write()` and 286062306a36Sopenharmony_ci:c:func:`snd_ac97_update()` functions are used to set a value to 286162306a36Sopenharmony_cithe given register (``AC97_XXX``). The difference between them is that 286262306a36Sopenharmony_ci:c:func:`snd_ac97_update()` doesn't write a value if the given 286362306a36Sopenharmony_civalue has been already set, while :c:func:`snd_ac97_write()` 286462306a36Sopenharmony_cialways rewrites the value:: 286562306a36Sopenharmony_ci 286662306a36Sopenharmony_ci snd_ac97_write(ac97, AC97_MASTER, 0x8080); 286762306a36Sopenharmony_ci snd_ac97_update(ac97, AC97_MASTER, 0x8080); 286862306a36Sopenharmony_ci 286962306a36Sopenharmony_ci:c:func:`snd_ac97_read()` is used to read the value of the given 287062306a36Sopenharmony_ciregister. For example:: 287162306a36Sopenharmony_ci 287262306a36Sopenharmony_ci value = snd_ac97_read(ac97, AC97_MASTER); 287362306a36Sopenharmony_ci 287462306a36Sopenharmony_ci:c:func:`snd_ac97_update_bits()` is used to update some bits in 287562306a36Sopenharmony_cithe given register:: 287662306a36Sopenharmony_ci 287762306a36Sopenharmony_ci snd_ac97_update_bits(ac97, reg, mask, value); 287862306a36Sopenharmony_ci 287962306a36Sopenharmony_ciAlso, there is a function to change the sample rate (of a given register 288062306a36Sopenharmony_cisuch as ``AC97_PCM_FRONT_DAC_RATE``) when VRA or DRA is supported by the 288162306a36Sopenharmony_cicodec: :c:func:`snd_ac97_set_rate()`:: 288262306a36Sopenharmony_ci 288362306a36Sopenharmony_ci snd_ac97_set_rate(ac97, AC97_PCM_FRONT_DAC_RATE, 44100); 288462306a36Sopenharmony_ci 288562306a36Sopenharmony_ci 288662306a36Sopenharmony_ciThe following registers are available to set the rate: 288762306a36Sopenharmony_ci``AC97_PCM_MIC_ADC_RATE``, ``AC97_PCM_FRONT_DAC_RATE``, 288862306a36Sopenharmony_ci``AC97_PCM_LR_ADC_RATE``, ``AC97_SPDIF``. When ``AC97_SPDIF`` is 288962306a36Sopenharmony_cispecified, the register is not really changed but the corresponding 289062306a36Sopenharmony_ciIEC958 status bits will be updated. 289162306a36Sopenharmony_ci 289262306a36Sopenharmony_ciClock Adjustment 289362306a36Sopenharmony_ci---------------- 289462306a36Sopenharmony_ci 289562306a36Sopenharmony_ciIn some chips, the clock of the codec isn't 48000 but using a PCI clock 289662306a36Sopenharmony_ci(to save a quartz!). In this case, change the field ``bus->clock`` to 289762306a36Sopenharmony_cithe corresponding value. For example, intel8x0 and es1968 drivers have 289862306a36Sopenharmony_citheir own function to read from the clock. 289962306a36Sopenharmony_ci 290062306a36Sopenharmony_ciProc Files 290162306a36Sopenharmony_ci---------- 290262306a36Sopenharmony_ci 290362306a36Sopenharmony_ciThe ALSA AC97 interface will create a proc file such as 290462306a36Sopenharmony_ci``/proc/asound/card0/codec97#0/ac97#0-0`` and ``ac97#0-0+regs``. You 290562306a36Sopenharmony_cican refer to these files to see the current status and registers of 290662306a36Sopenharmony_cithe codec. 290762306a36Sopenharmony_ci 290862306a36Sopenharmony_ciMultiple Codecs 290962306a36Sopenharmony_ci--------------- 291062306a36Sopenharmony_ci 291162306a36Sopenharmony_ciWhen there are several codecs on the same card, you need to call 291262306a36Sopenharmony_ci:c:func:`snd_ac97_mixer()` multiple times with ``ac97.num=1`` or 291362306a36Sopenharmony_cigreater. The ``num`` field specifies the codec number. 291462306a36Sopenharmony_ci 291562306a36Sopenharmony_ciIf you set up multiple codecs, you either need to write different 291662306a36Sopenharmony_cicallbacks for each codec or check ``ac97->num`` in the callback 291762306a36Sopenharmony_ciroutines. 291862306a36Sopenharmony_ci 291962306a36Sopenharmony_ciMIDI (MPU401-UART) Interface 292062306a36Sopenharmony_ci============================ 292162306a36Sopenharmony_ci 292262306a36Sopenharmony_ciGeneral 292362306a36Sopenharmony_ci------- 292462306a36Sopenharmony_ci 292562306a36Sopenharmony_ciMany soundcards have built-in MIDI (MPU401-UART) interfaces. When the 292662306a36Sopenharmony_cisoundcard supports the standard MPU401-UART interface, most likely you 292762306a36Sopenharmony_cican use the ALSA MPU401-UART API. The MPU401-UART API is defined in 292862306a36Sopenharmony_ci``<sound/mpu401.h>``. 292962306a36Sopenharmony_ci 293062306a36Sopenharmony_ciSome soundchips have a similar but slightly different implementation of 293162306a36Sopenharmony_cimpu401 stuff. For example, emu10k1 has its own mpu401 routines. 293262306a36Sopenharmony_ci 293362306a36Sopenharmony_ciMIDI Constructor 293462306a36Sopenharmony_ci---------------- 293562306a36Sopenharmony_ci 293662306a36Sopenharmony_ciTo create a rawmidi object, call :c:func:`snd_mpu401_uart_new()`:: 293762306a36Sopenharmony_ci 293862306a36Sopenharmony_ci struct snd_rawmidi *rmidi; 293962306a36Sopenharmony_ci snd_mpu401_uart_new(card, 0, MPU401_HW_MPU401, port, info_flags, 294062306a36Sopenharmony_ci irq, &rmidi); 294162306a36Sopenharmony_ci 294262306a36Sopenharmony_ci 294362306a36Sopenharmony_ciThe first argument is the card pointer, and the second is the index of 294462306a36Sopenharmony_cithis component. You can create up to 8 rawmidi devices. 294562306a36Sopenharmony_ci 294662306a36Sopenharmony_ciThe third argument is the type of the hardware, ``MPU401_HW_XXX``. If 294762306a36Sopenharmony_ciit's not a special one, you can use ``MPU401_HW_MPU401``. 294862306a36Sopenharmony_ci 294962306a36Sopenharmony_ciThe 4th argument is the I/O port address. Many backward-compatible 295062306a36Sopenharmony_ciMPU401 have an I/O port such as 0x330. Or, it might be a part of its own 295162306a36Sopenharmony_ciPCI I/O region. It depends on the chip design. 295262306a36Sopenharmony_ci 295362306a36Sopenharmony_ciThe 5th argument is a bitflag for additional information. When the I/O 295462306a36Sopenharmony_ciport address above is part of the PCI I/O region, the MPU401 I/O port 295562306a36Sopenharmony_cimight have been already allocated (reserved) by the driver itself. In 295662306a36Sopenharmony_cisuch a case, pass a bit flag ``MPU401_INFO_INTEGRATED``, and the 295762306a36Sopenharmony_cimpu401-uart layer will allocate the I/O ports by itself. 295862306a36Sopenharmony_ci 295962306a36Sopenharmony_ciWhen the controller supports only the input or output MIDI stream, pass 296062306a36Sopenharmony_cithe ``MPU401_INFO_INPUT`` or ``MPU401_INFO_OUTPUT`` bitflag, 296162306a36Sopenharmony_cirespectively. Then the rawmidi instance is created as a single stream. 296262306a36Sopenharmony_ci 296362306a36Sopenharmony_ci``MPU401_INFO_MMIO`` bitflag is used to change the access method to MMIO 296462306a36Sopenharmony_ci(via readb and writeb) instead of iob and outb. In this case, you have 296562306a36Sopenharmony_cito pass the iomapped address to :c:func:`snd_mpu401_uart_new()`. 296662306a36Sopenharmony_ci 296762306a36Sopenharmony_ciWhen ``MPU401_INFO_TX_IRQ`` is set, the output stream isn't checked in 296862306a36Sopenharmony_cithe default interrupt handler. The driver needs to call 296962306a36Sopenharmony_ci:c:func:`snd_mpu401_uart_interrupt_tx()` by itself to start 297062306a36Sopenharmony_ciprocessing the output stream in the irq handler. 297162306a36Sopenharmony_ci 297262306a36Sopenharmony_ciIf the MPU-401 interface shares its interrupt with the other logical 297362306a36Sopenharmony_cidevices on the card, set ``MPU401_INFO_IRQ_HOOK`` (see 297462306a36Sopenharmony_ci`below <MIDI Interrupt Handler_>`__). 297562306a36Sopenharmony_ci 297662306a36Sopenharmony_ciUsually, the port address corresponds to the command port and port + 1 297762306a36Sopenharmony_cicorresponds to the data port. If not, you may change the ``cport`` 297862306a36Sopenharmony_cifield of struct snd_mpu401 manually afterward. 297962306a36Sopenharmony_ciHowever, struct snd_mpu401 pointer is 298062306a36Sopenharmony_cinot returned explicitly by :c:func:`snd_mpu401_uart_new()`. You 298162306a36Sopenharmony_cineed to cast ``rmidi->private_data`` to struct snd_mpu401 explicitly:: 298262306a36Sopenharmony_ci 298362306a36Sopenharmony_ci struct snd_mpu401 *mpu; 298462306a36Sopenharmony_ci mpu = rmidi->private_data; 298562306a36Sopenharmony_ci 298662306a36Sopenharmony_ciand reset the ``cport`` as you like:: 298762306a36Sopenharmony_ci 298862306a36Sopenharmony_ci mpu->cport = my_own_control_port; 298962306a36Sopenharmony_ci 299062306a36Sopenharmony_ciThe 6th argument specifies the ISA irq number that will be allocated. If 299162306a36Sopenharmony_cino interrupt is to be allocated (because your code is already allocating 299262306a36Sopenharmony_cia shared interrupt, or because the device does not use interrupts), pass 299362306a36Sopenharmony_ci-1 instead. For a MPU-401 device without an interrupt, a polling timer 299462306a36Sopenharmony_ciwill be used instead. 299562306a36Sopenharmony_ci 299662306a36Sopenharmony_ciMIDI Interrupt Handler 299762306a36Sopenharmony_ci---------------------- 299862306a36Sopenharmony_ci 299962306a36Sopenharmony_ciWhen the interrupt is allocated in 300062306a36Sopenharmony_ci:c:func:`snd_mpu401_uart_new()`, an exclusive ISA interrupt 300162306a36Sopenharmony_cihandler is automatically used, hence you don't have anything else to do 300262306a36Sopenharmony_cithan creating the mpu401 stuff. Otherwise, you have to set 300362306a36Sopenharmony_ci``MPU401_INFO_IRQ_HOOK``, and call 300462306a36Sopenharmony_ci:c:func:`snd_mpu401_uart_interrupt()` explicitly from your own 300562306a36Sopenharmony_ciinterrupt handler when it has determined that a UART interrupt has 300662306a36Sopenharmony_cioccurred. 300762306a36Sopenharmony_ci 300862306a36Sopenharmony_ciIn this case, you need to pass the private_data of the returned rawmidi 300962306a36Sopenharmony_ciobject from :c:func:`snd_mpu401_uart_new()` as the second 301062306a36Sopenharmony_ciargument of :c:func:`snd_mpu401_uart_interrupt()`:: 301162306a36Sopenharmony_ci 301262306a36Sopenharmony_ci snd_mpu401_uart_interrupt(irq, rmidi->private_data, regs); 301362306a36Sopenharmony_ci 301462306a36Sopenharmony_ci 301562306a36Sopenharmony_ciRawMIDI Interface 301662306a36Sopenharmony_ci================= 301762306a36Sopenharmony_ci 301862306a36Sopenharmony_ciOverview 301962306a36Sopenharmony_ci-------- 302062306a36Sopenharmony_ci 302162306a36Sopenharmony_ciThe raw MIDI interface is used for hardware MIDI ports that can be 302262306a36Sopenharmony_ciaccessed as a byte stream. It is not used for synthesizer chips that do 302362306a36Sopenharmony_cinot directly understand MIDI. 302462306a36Sopenharmony_ci 302562306a36Sopenharmony_ciALSA handles file and buffer management. All you have to do is to write 302662306a36Sopenharmony_cisome code to move data between the buffer and the hardware. 302762306a36Sopenharmony_ci 302862306a36Sopenharmony_ciThe rawmidi API is defined in ``<sound/rawmidi.h>``. 302962306a36Sopenharmony_ci 303062306a36Sopenharmony_ciRawMIDI Constructor 303162306a36Sopenharmony_ci------------------- 303262306a36Sopenharmony_ci 303362306a36Sopenharmony_ciTo create a rawmidi device, call the :c:func:`snd_rawmidi_new()` 303462306a36Sopenharmony_cifunction:: 303562306a36Sopenharmony_ci 303662306a36Sopenharmony_ci struct snd_rawmidi *rmidi; 303762306a36Sopenharmony_ci err = snd_rawmidi_new(chip->card, "MyMIDI", 0, outs, ins, &rmidi); 303862306a36Sopenharmony_ci if (err < 0) 303962306a36Sopenharmony_ci return err; 304062306a36Sopenharmony_ci rmidi->private_data = chip; 304162306a36Sopenharmony_ci strcpy(rmidi->name, "My MIDI"); 304262306a36Sopenharmony_ci rmidi->info_flags = SNDRV_RAWMIDI_INFO_OUTPUT | 304362306a36Sopenharmony_ci SNDRV_RAWMIDI_INFO_INPUT | 304462306a36Sopenharmony_ci SNDRV_RAWMIDI_INFO_DUPLEX; 304562306a36Sopenharmony_ci 304662306a36Sopenharmony_ciThe first argument is the card pointer, the second argument is the ID 304762306a36Sopenharmony_cistring. 304862306a36Sopenharmony_ci 304962306a36Sopenharmony_ciThe third argument is the index of this component. You can create up to 305062306a36Sopenharmony_ci8 rawmidi devices. 305162306a36Sopenharmony_ci 305262306a36Sopenharmony_ciThe fourth and fifth arguments are the number of output and input 305362306a36Sopenharmony_cisubstreams, respectively, of this device (a substream is the equivalent 305462306a36Sopenharmony_ciof a MIDI port). 305562306a36Sopenharmony_ci 305662306a36Sopenharmony_ciSet the ``info_flags`` field to specify the capabilities of the 305762306a36Sopenharmony_cidevice. Set ``SNDRV_RAWMIDI_INFO_OUTPUT`` if there is at least one 305862306a36Sopenharmony_cioutput port, ``SNDRV_RAWMIDI_INFO_INPUT`` if there is at least one 305962306a36Sopenharmony_ciinput port, and ``SNDRV_RAWMIDI_INFO_DUPLEX`` if the device can handle 306062306a36Sopenharmony_cioutput and input at the same time. 306162306a36Sopenharmony_ci 306262306a36Sopenharmony_ciAfter the rawmidi device is created, you need to set the operators 306362306a36Sopenharmony_ci(callbacks) for each substream. There are helper functions to set the 306462306a36Sopenharmony_cioperators for all the substreams of a device:: 306562306a36Sopenharmony_ci 306662306a36Sopenharmony_ci snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_OUTPUT, &snd_mymidi_output_ops); 306762306a36Sopenharmony_ci snd_rawmidi_set_ops(rmidi, SNDRV_RAWMIDI_STREAM_INPUT, &snd_mymidi_input_ops); 306862306a36Sopenharmony_ci 306962306a36Sopenharmony_ciThe operators are usually defined like this:: 307062306a36Sopenharmony_ci 307162306a36Sopenharmony_ci static struct snd_rawmidi_ops snd_mymidi_output_ops = { 307262306a36Sopenharmony_ci .open = snd_mymidi_output_open, 307362306a36Sopenharmony_ci .close = snd_mymidi_output_close, 307462306a36Sopenharmony_ci .trigger = snd_mymidi_output_trigger, 307562306a36Sopenharmony_ci }; 307662306a36Sopenharmony_ci 307762306a36Sopenharmony_ciThese callbacks are explained in the `RawMIDI Callbacks`_ section. 307862306a36Sopenharmony_ci 307962306a36Sopenharmony_ciIf there are more than one substream, you should give a unique name to 308062306a36Sopenharmony_cieach of them:: 308162306a36Sopenharmony_ci 308262306a36Sopenharmony_ci struct snd_rawmidi_substream *substream; 308362306a36Sopenharmony_ci list_for_each_entry(substream, 308462306a36Sopenharmony_ci &rmidi->streams[SNDRV_RAWMIDI_STREAM_OUTPUT].substreams, 308562306a36Sopenharmony_ci list { 308662306a36Sopenharmony_ci sprintf(substream->name, "My MIDI Port %d", substream->number + 1); 308762306a36Sopenharmony_ci } 308862306a36Sopenharmony_ci /* same for SNDRV_RAWMIDI_STREAM_INPUT */ 308962306a36Sopenharmony_ci 309062306a36Sopenharmony_ciRawMIDI Callbacks 309162306a36Sopenharmony_ci----------------- 309262306a36Sopenharmony_ci 309362306a36Sopenharmony_ciIn all the callbacks, the private data that you've set for the rawmidi 309462306a36Sopenharmony_cidevice can be accessed as ``substream->rmidi->private_data``. 309562306a36Sopenharmony_ci 309662306a36Sopenharmony_ciIf there is more than one port, your callbacks can determine the port 309762306a36Sopenharmony_ciindex from the struct snd_rawmidi_substream data passed to each 309862306a36Sopenharmony_cicallback:: 309962306a36Sopenharmony_ci 310062306a36Sopenharmony_ci struct snd_rawmidi_substream *substream; 310162306a36Sopenharmony_ci int index = substream->number; 310262306a36Sopenharmony_ci 310362306a36Sopenharmony_ciRawMIDI open callback 310462306a36Sopenharmony_ci~~~~~~~~~~~~~~~~~~~~~ 310562306a36Sopenharmony_ci 310662306a36Sopenharmony_ci:: 310762306a36Sopenharmony_ci 310862306a36Sopenharmony_ci static int snd_xxx_open(struct snd_rawmidi_substream *substream); 310962306a36Sopenharmony_ci 311062306a36Sopenharmony_ci 311162306a36Sopenharmony_ciThis is called when a substream is opened. You can initialize the 311262306a36Sopenharmony_cihardware here, but you shouldn't start transmitting/receiving data yet. 311362306a36Sopenharmony_ci 311462306a36Sopenharmony_ciRawMIDI close callback 311562306a36Sopenharmony_ci~~~~~~~~~~~~~~~~~~~~~~ 311662306a36Sopenharmony_ci 311762306a36Sopenharmony_ci:: 311862306a36Sopenharmony_ci 311962306a36Sopenharmony_ci static int snd_xxx_close(struct snd_rawmidi_substream *substream); 312062306a36Sopenharmony_ci 312162306a36Sopenharmony_ciGuess what. 312262306a36Sopenharmony_ci 312362306a36Sopenharmony_ciThe ``open`` and ``close`` callbacks of a rawmidi device are 312462306a36Sopenharmony_ciserialized with a mutex, and can sleep. 312562306a36Sopenharmony_ci 312662306a36Sopenharmony_ciRawmidi trigger callback for output substreams 312762306a36Sopenharmony_ci~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 312862306a36Sopenharmony_ci 312962306a36Sopenharmony_ci:: 313062306a36Sopenharmony_ci 313162306a36Sopenharmony_ci static void snd_xxx_output_trigger(struct snd_rawmidi_substream *substream, int up); 313262306a36Sopenharmony_ci 313362306a36Sopenharmony_ci 313462306a36Sopenharmony_ciThis is called with a nonzero ``up`` parameter when there is some data 313562306a36Sopenharmony_ciin the substream buffer that must be transmitted. 313662306a36Sopenharmony_ci 313762306a36Sopenharmony_ciTo read data from the buffer, call 313862306a36Sopenharmony_ci:c:func:`snd_rawmidi_transmit_peek()`. It will return the number 313962306a36Sopenharmony_ciof bytes that have been read; this will be less than the number of bytes 314062306a36Sopenharmony_cirequested when there are no more data in the buffer. After the data have 314162306a36Sopenharmony_cibeen transmitted successfully, call 314262306a36Sopenharmony_ci:c:func:`snd_rawmidi_transmit_ack()` to remove the data from the 314362306a36Sopenharmony_cisubstream buffer:: 314462306a36Sopenharmony_ci 314562306a36Sopenharmony_ci unsigned char data; 314662306a36Sopenharmony_ci while (snd_rawmidi_transmit_peek(substream, &data, 1) == 1) { 314762306a36Sopenharmony_ci if (snd_mychip_try_to_transmit(data)) 314862306a36Sopenharmony_ci snd_rawmidi_transmit_ack(substream, 1); 314962306a36Sopenharmony_ci else 315062306a36Sopenharmony_ci break; /* hardware FIFO full */ 315162306a36Sopenharmony_ci } 315262306a36Sopenharmony_ci 315362306a36Sopenharmony_ciIf you know beforehand that the hardware will accept data, you can use 315462306a36Sopenharmony_cithe :c:func:`snd_rawmidi_transmit()` function which reads some 315562306a36Sopenharmony_cidata and removes them from the buffer at once:: 315662306a36Sopenharmony_ci 315762306a36Sopenharmony_ci while (snd_mychip_transmit_possible()) { 315862306a36Sopenharmony_ci unsigned char data; 315962306a36Sopenharmony_ci if (snd_rawmidi_transmit(substream, &data, 1) != 1) 316062306a36Sopenharmony_ci break; /* no more data */ 316162306a36Sopenharmony_ci snd_mychip_transmit(data); 316262306a36Sopenharmony_ci } 316362306a36Sopenharmony_ci 316462306a36Sopenharmony_ciIf you know beforehand how many bytes you can accept, you can use a 316562306a36Sopenharmony_cibuffer size greater than one with the ``snd_rawmidi_transmit*()`` functions. 316662306a36Sopenharmony_ci 316762306a36Sopenharmony_ciThe ``trigger`` callback must not sleep. If the hardware FIFO is full 316862306a36Sopenharmony_cibefore the substream buffer has been emptied, you have to continue 316962306a36Sopenharmony_citransmitting data later, either in an interrupt handler, or with a 317062306a36Sopenharmony_citimer if the hardware doesn't have a MIDI transmit interrupt. 317162306a36Sopenharmony_ci 317262306a36Sopenharmony_ciThe ``trigger`` callback is called with a zero ``up`` parameter when 317362306a36Sopenharmony_cithe transmission of data should be aborted. 317462306a36Sopenharmony_ci 317562306a36Sopenharmony_ciRawMIDI trigger callback for input substreams 317662306a36Sopenharmony_ci~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 317762306a36Sopenharmony_ci 317862306a36Sopenharmony_ci:: 317962306a36Sopenharmony_ci 318062306a36Sopenharmony_ci static void snd_xxx_input_trigger(struct snd_rawmidi_substream *substream, int up); 318162306a36Sopenharmony_ci 318262306a36Sopenharmony_ci 318362306a36Sopenharmony_ciThis is called with a nonzero ``up`` parameter to enable receiving data, 318462306a36Sopenharmony_cior with a zero ``up`` parameter do disable receiving data. 318562306a36Sopenharmony_ci 318662306a36Sopenharmony_ciThe ``trigger`` callback must not sleep; the actual reading of data 318762306a36Sopenharmony_cifrom the device is usually done in an interrupt handler. 318862306a36Sopenharmony_ci 318962306a36Sopenharmony_ciWhen data reception is enabled, your interrupt handler should call 319062306a36Sopenharmony_ci:c:func:`snd_rawmidi_receive()` for all received data:: 319162306a36Sopenharmony_ci 319262306a36Sopenharmony_ci void snd_mychip_midi_interrupt(...) 319362306a36Sopenharmony_ci { 319462306a36Sopenharmony_ci while (mychip_midi_available()) { 319562306a36Sopenharmony_ci unsigned char data; 319662306a36Sopenharmony_ci data = mychip_midi_read(); 319762306a36Sopenharmony_ci snd_rawmidi_receive(substream, &data, 1); 319862306a36Sopenharmony_ci } 319962306a36Sopenharmony_ci } 320062306a36Sopenharmony_ci 320162306a36Sopenharmony_ci 320262306a36Sopenharmony_cidrain callback 320362306a36Sopenharmony_ci~~~~~~~~~~~~~~ 320462306a36Sopenharmony_ci 320562306a36Sopenharmony_ci:: 320662306a36Sopenharmony_ci 320762306a36Sopenharmony_ci static void snd_xxx_drain(struct snd_rawmidi_substream *substream); 320862306a36Sopenharmony_ci 320962306a36Sopenharmony_ci 321062306a36Sopenharmony_ciThis is only used with output substreams. This function should wait 321162306a36Sopenharmony_ciuntil all data read from the substream buffer have been transmitted. 321262306a36Sopenharmony_ciThis ensures that the device can be closed and the driver unloaded 321362306a36Sopenharmony_ciwithout losing data. 321462306a36Sopenharmony_ci 321562306a36Sopenharmony_ciThis callback is optional. If you do not set ``drain`` in the struct 321662306a36Sopenharmony_cisnd_rawmidi_ops structure, ALSA will simply wait for 50 milliseconds 321762306a36Sopenharmony_ciinstead. 321862306a36Sopenharmony_ci 321962306a36Sopenharmony_ciMiscellaneous Devices 322062306a36Sopenharmony_ci===================== 322162306a36Sopenharmony_ci 322262306a36Sopenharmony_ciFM OPL3 322362306a36Sopenharmony_ci------- 322462306a36Sopenharmony_ci 322562306a36Sopenharmony_ciThe FM OPL3 is still used in many chips (mainly for backward 322662306a36Sopenharmony_cicompatibility). ALSA has a nice OPL3 FM control layer, too. The OPL3 API 322762306a36Sopenharmony_ciis defined in ``<sound/opl3.h>``. 322862306a36Sopenharmony_ci 322962306a36Sopenharmony_ciFM registers can be directly accessed through the direct-FM API, defined 323062306a36Sopenharmony_ciin ``<sound/asound_fm.h>``. In ALSA native mode, FM registers are 323162306a36Sopenharmony_ciaccessed through the Hardware-Dependent Device direct-FM extension API, 323262306a36Sopenharmony_ciwhereas in OSS compatible mode, FM registers can be accessed with the 323362306a36Sopenharmony_ciOSS direct-FM compatible API in ``/dev/dmfmX`` device. 323462306a36Sopenharmony_ci 323562306a36Sopenharmony_ciTo create the OPL3 component, you have two functions to call. The first 323662306a36Sopenharmony_cione is a constructor for the ``opl3_t`` instance:: 323762306a36Sopenharmony_ci 323862306a36Sopenharmony_ci struct snd_opl3 *opl3; 323962306a36Sopenharmony_ci snd_opl3_create(card, lport, rport, OPL3_HW_OPL3_XXX, 324062306a36Sopenharmony_ci integrated, &opl3); 324162306a36Sopenharmony_ci 324262306a36Sopenharmony_ciThe first argument is the card pointer, the second one is the left port 324362306a36Sopenharmony_ciaddress, and the third is the right port address. In most cases, the 324462306a36Sopenharmony_ciright port is placed at the left port + 2. 324562306a36Sopenharmony_ci 324662306a36Sopenharmony_ciThe fourth argument is the hardware type. 324762306a36Sopenharmony_ci 324862306a36Sopenharmony_ciWhen the left and right ports have been already allocated by the card 324962306a36Sopenharmony_cidriver, pass non-zero to the fifth argument (``integrated``). Otherwise, 325062306a36Sopenharmony_cithe opl3 module will allocate the specified ports by itself. 325162306a36Sopenharmony_ci 325262306a36Sopenharmony_ciWhen the accessing the hardware requires special method instead of the 325362306a36Sopenharmony_cistandard I/O access, you can create opl3 instance separately with 325462306a36Sopenharmony_ci:c:func:`snd_opl3_new()`:: 325562306a36Sopenharmony_ci 325662306a36Sopenharmony_ci struct snd_opl3 *opl3; 325762306a36Sopenharmony_ci snd_opl3_new(card, OPL3_HW_OPL3_XXX, &opl3); 325862306a36Sopenharmony_ci 325962306a36Sopenharmony_ciThen set ``command``, ``private_data`` and ``private_free`` for the 326062306a36Sopenharmony_ciprivate access function, the private data and the destructor. The 326162306a36Sopenharmony_ci``l_port`` and ``r_port`` are not necessarily set. Only the command 326262306a36Sopenharmony_cimust be set properly. You can retrieve the data from the 326362306a36Sopenharmony_ci``opl3->private_data`` field. 326462306a36Sopenharmony_ci 326562306a36Sopenharmony_ciAfter creating the opl3 instance via :c:func:`snd_opl3_new()`, 326662306a36Sopenharmony_cicall :c:func:`snd_opl3_init()` to initialize the chip to the 326762306a36Sopenharmony_ciproper state. Note that :c:func:`snd_opl3_create()` always calls 326862306a36Sopenharmony_ciit internally. 326962306a36Sopenharmony_ci 327062306a36Sopenharmony_ciIf the opl3 instance is created successfully, then create a hwdep device 327162306a36Sopenharmony_cifor this opl3:: 327262306a36Sopenharmony_ci 327362306a36Sopenharmony_ci struct snd_hwdep *opl3hwdep; 327462306a36Sopenharmony_ci snd_opl3_hwdep_new(opl3, 0, 1, &opl3hwdep); 327562306a36Sopenharmony_ci 327662306a36Sopenharmony_ciThe first argument is the ``opl3_t`` instance you created, and the 327762306a36Sopenharmony_cisecond is the index number, usually 0. 327862306a36Sopenharmony_ci 327962306a36Sopenharmony_ciThe third argument is the index-offset for the sequencer client assigned 328062306a36Sopenharmony_cito the OPL3 port. When there is an MPU401-UART, give 1 for here (UART 328162306a36Sopenharmony_cialways takes 0). 328262306a36Sopenharmony_ci 328362306a36Sopenharmony_ciHardware-Dependent Devices 328462306a36Sopenharmony_ci-------------------------- 328562306a36Sopenharmony_ci 328662306a36Sopenharmony_ciSome chips need user-space access for special controls or for loading 328762306a36Sopenharmony_cithe micro code. In such a case, you can create a hwdep 328862306a36Sopenharmony_ci(hardware-dependent) device. The hwdep API is defined in 328962306a36Sopenharmony_ci``<sound/hwdep.h>``. You can find examples in opl3 driver or 329062306a36Sopenharmony_ci``isa/sb/sb16_csp.c``. 329162306a36Sopenharmony_ci 329262306a36Sopenharmony_ciThe creation of the ``hwdep`` instance is done via 329362306a36Sopenharmony_ci:c:func:`snd_hwdep_new()`:: 329462306a36Sopenharmony_ci 329562306a36Sopenharmony_ci struct snd_hwdep *hw; 329662306a36Sopenharmony_ci snd_hwdep_new(card, "My HWDEP", 0, &hw); 329762306a36Sopenharmony_ci 329862306a36Sopenharmony_ciwhere the third argument is the index number. 329962306a36Sopenharmony_ci 330062306a36Sopenharmony_ciYou can then pass any pointer value to the ``private_data``. If you 330162306a36Sopenharmony_ciassign private data, you should define a destructor, too. The 330262306a36Sopenharmony_cidestructor function is set in the ``private_free`` field:: 330362306a36Sopenharmony_ci 330462306a36Sopenharmony_ci struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL); 330562306a36Sopenharmony_ci hw->private_data = p; 330662306a36Sopenharmony_ci hw->private_free = mydata_free; 330762306a36Sopenharmony_ci 330862306a36Sopenharmony_ciand the implementation of the destructor would be:: 330962306a36Sopenharmony_ci 331062306a36Sopenharmony_ci static void mydata_free(struct snd_hwdep *hw) 331162306a36Sopenharmony_ci { 331262306a36Sopenharmony_ci struct mydata *p = hw->private_data; 331362306a36Sopenharmony_ci kfree(p); 331462306a36Sopenharmony_ci } 331562306a36Sopenharmony_ci 331662306a36Sopenharmony_ciThe arbitrary file operations can be defined for this instance. The file 331762306a36Sopenharmony_cioperators are defined in the ``ops`` table. For example, assume that 331862306a36Sopenharmony_cithis chip needs an ioctl:: 331962306a36Sopenharmony_ci 332062306a36Sopenharmony_ci hw->ops.open = mydata_open; 332162306a36Sopenharmony_ci hw->ops.ioctl = mydata_ioctl; 332262306a36Sopenharmony_ci hw->ops.release = mydata_release; 332362306a36Sopenharmony_ci 332462306a36Sopenharmony_ciAnd implement the callback functions as you like. 332562306a36Sopenharmony_ci 332662306a36Sopenharmony_ciIEC958 (S/PDIF) 332762306a36Sopenharmony_ci--------------- 332862306a36Sopenharmony_ci 332962306a36Sopenharmony_ciUsually the controls for IEC958 devices are implemented via the control 333062306a36Sopenharmony_ciinterface. There is a macro to compose a name string for IEC958 333162306a36Sopenharmony_cicontrols, :c:func:`SNDRV_CTL_NAME_IEC958()` defined in 333262306a36Sopenharmony_ci``<include/asound.h>``. 333362306a36Sopenharmony_ci 333462306a36Sopenharmony_ciThere are some standard controls for IEC958 status bits. These controls 333562306a36Sopenharmony_ciuse the type ``SNDRV_CTL_ELEM_TYPE_IEC958``, and the size of element is 333662306a36Sopenharmony_cifixed as 4 bytes array (value.iec958.status[x]). For the ``info`` 333762306a36Sopenharmony_cicallback, you don't specify the value field for this type (the count 333862306a36Sopenharmony_cifield must be set, though). 333962306a36Sopenharmony_ci 334062306a36Sopenharmony_ci“IEC958 Playback Con Mask” is used to return the bit-mask for the IEC958 334162306a36Sopenharmony_cistatus bits of consumer mode. Similarly, “IEC958 Playback Pro Mask” 334262306a36Sopenharmony_cireturns the bitmask for professional mode. They are read-only controls. 334362306a36Sopenharmony_ci 334462306a36Sopenharmony_ciMeanwhile, “IEC958 Playback Default” control is defined for getting and 334562306a36Sopenharmony_cisetting the current default IEC958 bits. 334662306a36Sopenharmony_ci 334762306a36Sopenharmony_ciDue to historical reasons, both variants of the Playback Mask and the 334862306a36Sopenharmony_ciPlayback Default controls can be implemented on either a 334962306a36Sopenharmony_ci``SNDRV_CTL_ELEM_IFACE_PCM`` or a ``SNDRV_CTL_ELEM_IFACE_MIXER`` iface. 335062306a36Sopenharmony_ciDrivers should expose the mask and default on the same iface though. 335162306a36Sopenharmony_ci 335262306a36Sopenharmony_ciIn addition, you can define the control switches to enable/disable or to 335362306a36Sopenharmony_ciset the raw bit mode. The implementation will depend on the chip, but 335462306a36Sopenharmony_cithe control should be named as “IEC958 xxx”, preferably using the 335562306a36Sopenharmony_ci:c:func:`SNDRV_CTL_NAME_IEC958()` macro. 335662306a36Sopenharmony_ci 335762306a36Sopenharmony_ciYou can find several cases, for example, ``pci/emu10k1``, 335862306a36Sopenharmony_ci``pci/ice1712``, or ``pci/cmipci.c``. 335962306a36Sopenharmony_ci 336062306a36Sopenharmony_ciBuffer and Memory Management 336162306a36Sopenharmony_ci============================ 336262306a36Sopenharmony_ci 336362306a36Sopenharmony_ciBuffer Types 336462306a36Sopenharmony_ci------------ 336562306a36Sopenharmony_ci 336662306a36Sopenharmony_ciALSA provides several different buffer allocation functions depending on 336762306a36Sopenharmony_cithe bus and the architecture. All these have a consistent API. The 336862306a36Sopenharmony_ciallocation of physically-contiguous pages is done via the 336962306a36Sopenharmony_ci:c:func:`snd_malloc_xxx_pages()` function, where xxx is the bus 337062306a36Sopenharmony_citype. 337162306a36Sopenharmony_ci 337262306a36Sopenharmony_ciThe allocation of pages with fallback is done via 337362306a36Sopenharmony_ci:c:func:`snd_dma_alloc_pages_fallback()`. This function tries 337462306a36Sopenharmony_cito allocate the specified number of pages, but if not enough pages are 337562306a36Sopenharmony_ciavailable, it tries to reduce the request size until enough space 337662306a36Sopenharmony_ciis found, down to one page. 337762306a36Sopenharmony_ci 337862306a36Sopenharmony_ciTo release the pages, call the :c:func:`snd_dma_free_pages()` 337962306a36Sopenharmony_cifunction. 338062306a36Sopenharmony_ci 338162306a36Sopenharmony_ciUsually, ALSA drivers try to allocate and reserve a large contiguous 338262306a36Sopenharmony_ciphysical space at the time the module is loaded for later use. This 338362306a36Sopenharmony_ciis called “pre-allocation”. As already written, you can call the 338462306a36Sopenharmony_cifollowing function at PCM instance construction time (in the case of PCI 338562306a36Sopenharmony_cibus):: 338662306a36Sopenharmony_ci 338762306a36Sopenharmony_ci snd_pcm_lib_preallocate_pages_for_all(pcm, SNDRV_DMA_TYPE_DEV, 338862306a36Sopenharmony_ci &pci->dev, size, max); 338962306a36Sopenharmony_ci 339062306a36Sopenharmony_ciwhere ``size`` is the byte size to be pre-allocated and ``max`` is 339162306a36Sopenharmony_cithe maximum size settable via the ``prealloc`` proc file. The 339262306a36Sopenharmony_ciallocator will try to get an area as large as possible within the 339362306a36Sopenharmony_cigiven size. 339462306a36Sopenharmony_ci 339562306a36Sopenharmony_ciThe second argument (type) and the third argument (device pointer) are 339662306a36Sopenharmony_cidependent on the bus. For normal devices, pass the device pointer 339762306a36Sopenharmony_ci(typically identical as ``card->dev``) to the third argument with 339862306a36Sopenharmony_ci``SNDRV_DMA_TYPE_DEV`` type. 339962306a36Sopenharmony_ci 340062306a36Sopenharmony_ciA continuous buffer unrelated to the 340162306a36Sopenharmony_cibus can be pre-allocated with ``SNDRV_DMA_TYPE_CONTINUOUS`` type. 340262306a36Sopenharmony_ciYou can pass NULL to the device pointer in that case, which is the 340362306a36Sopenharmony_cidefault mode implying to allocate with the ``GFP_KERNEL`` flag. 340462306a36Sopenharmony_ciIf you need a restricted (lower) address, set up the coherent DMA mask 340562306a36Sopenharmony_cibits for the device, and pass the device pointer, like the normal 340662306a36Sopenharmony_cidevice memory allocations. For this type, it's still allowed to pass 340762306a36Sopenharmony_ciNULL to the device pointer, too, if no address restriction is needed. 340862306a36Sopenharmony_ci 340962306a36Sopenharmony_ciFor the scatter-gather buffers, use ``SNDRV_DMA_TYPE_DEV_SG`` with the 341062306a36Sopenharmony_cidevice pointer (see the `Non-Contiguous Buffers`_ section). 341162306a36Sopenharmony_ci 341262306a36Sopenharmony_ciOnce the buffer is pre-allocated, you can use the allocator in the 341362306a36Sopenharmony_ci``hw_params`` callback:: 341462306a36Sopenharmony_ci 341562306a36Sopenharmony_ci snd_pcm_lib_malloc_pages(substream, size); 341662306a36Sopenharmony_ci 341762306a36Sopenharmony_ciNote that you have to pre-allocate to use this function. 341862306a36Sopenharmony_ci 341962306a36Sopenharmony_ciBut most drivers use the "managed buffer allocation mode" instead 342062306a36Sopenharmony_ciof manual allocation and release. 342162306a36Sopenharmony_ciThis is done by calling :c:func:`snd_pcm_set_managed_buffer_all()` 342262306a36Sopenharmony_ciinstead of :c:func:`snd_pcm_lib_preallocate_pages_for_all()`:: 342362306a36Sopenharmony_ci 342462306a36Sopenharmony_ci snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV, 342562306a36Sopenharmony_ci &pci->dev, size, max); 342662306a36Sopenharmony_ci 342762306a36Sopenharmony_ciwhere the passed arguments are identical for both functions. 342862306a36Sopenharmony_ciThe difference in the managed mode is that PCM core will call 342962306a36Sopenharmony_ci:c:func:`snd_pcm_lib_malloc_pages()` internally already before calling 343062306a36Sopenharmony_cithe PCM ``hw_params`` callback, and call :c:func:`snd_pcm_lib_free_pages()` 343162306a36Sopenharmony_ciafter the PCM ``hw_free`` callback automatically. So the driver 343262306a36Sopenharmony_cidoesn't have to call these functions explicitly in its callback any 343362306a36Sopenharmony_cilonger. This allows many drivers to have NULL ``hw_params`` and 343462306a36Sopenharmony_ci``hw_free`` entries. 343562306a36Sopenharmony_ci 343662306a36Sopenharmony_ciExternal Hardware Buffers 343762306a36Sopenharmony_ci------------------------- 343862306a36Sopenharmony_ci 343962306a36Sopenharmony_ciSome chips have their own hardware buffers and DMA transfer from the 344062306a36Sopenharmony_cihost memory is not available. In such a case, you need to either 1) 344162306a36Sopenharmony_cicopy/set the audio data directly to the external hardware buffer, or 2) 344262306a36Sopenharmony_cimake an intermediate buffer and copy/set the data from it to the 344362306a36Sopenharmony_ciexternal hardware buffer in interrupts (or in tasklets, preferably). 344462306a36Sopenharmony_ci 344562306a36Sopenharmony_ciThe first case works fine if the external hardware buffer is large 344662306a36Sopenharmony_cienough. This method doesn't need any extra buffers and thus is more 344762306a36Sopenharmony_ciefficient. You need to define the ``copy`` callback 344862306a36Sopenharmony_cifor the data transfer, in addition to the ``fill_silence`` 344962306a36Sopenharmony_cicallback for playback. However, there is a drawback: it cannot be 345062306a36Sopenharmony_cimmapped. The examples are GUS's GF1 PCM or emu8000's wavetable PCM. 345162306a36Sopenharmony_ci 345262306a36Sopenharmony_ciThe second case allows for mmap on the buffer, although you have to 345362306a36Sopenharmony_cihandle an interrupt or a tasklet to transfer the data from the 345462306a36Sopenharmony_ciintermediate buffer to the hardware buffer. You can find an example in 345562306a36Sopenharmony_cithe vxpocket driver. 345662306a36Sopenharmony_ci 345762306a36Sopenharmony_ciAnother case is when the chip uses a PCI memory-map region for the 345862306a36Sopenharmony_cibuffer instead of the host memory. In this case, mmap is available only 345962306a36Sopenharmony_cion certain architectures like the Intel one. In non-mmap mode, the data 346062306a36Sopenharmony_cicannot be transferred as in the normal way. Thus you need to define the 346162306a36Sopenharmony_ci``copy`` and ``fill_silence`` callbacks as well, 346262306a36Sopenharmony_cias in the cases above. Examples are found in ``rme32.c`` and 346362306a36Sopenharmony_ci``rme96.c``. 346462306a36Sopenharmony_ci 346562306a36Sopenharmony_ciThe implementation of the ``copy`` and 346662306a36Sopenharmony_ci``silence`` callbacks depends upon whether the hardware supports 346762306a36Sopenharmony_ciinterleaved or non-interleaved samples. The ``copy`` callback is 346862306a36Sopenharmony_cidefined like below, a bit differently depending on whether the direction 346962306a36Sopenharmony_ciis playback or capture:: 347062306a36Sopenharmony_ci 347162306a36Sopenharmony_ci static int playback_copy(struct snd_pcm_substream *substream, 347262306a36Sopenharmony_ci int channel, unsigned long pos, 347362306a36Sopenharmony_ci struct iov_iter *src, unsigned long count); 347462306a36Sopenharmony_ci static int capture_copy(struct snd_pcm_substream *substream, 347562306a36Sopenharmony_ci int channel, unsigned long pos, 347662306a36Sopenharmony_ci struct iov_iter *dst, unsigned long count); 347762306a36Sopenharmony_ci 347862306a36Sopenharmony_ciIn the case of interleaved samples, the second argument (``channel``) is 347962306a36Sopenharmony_cinot used. The third argument (``pos``) specifies the position in bytes. 348062306a36Sopenharmony_ci 348162306a36Sopenharmony_ciThe meaning of the fourth argument is different between playback and 348262306a36Sopenharmony_cicapture. For playback, it holds the source data pointer, and for 348362306a36Sopenharmony_cicapture, it's the destination data pointer. 348462306a36Sopenharmony_ci 348562306a36Sopenharmony_ciThe last argument is the number of bytes to be copied. 348662306a36Sopenharmony_ci 348762306a36Sopenharmony_ciWhat you have to do in this callback is again different between playback 348862306a36Sopenharmony_ciand capture directions. In the playback case, you copy the given amount 348962306a36Sopenharmony_ciof data (``count``) at the specified pointer (``src``) to the specified 349062306a36Sopenharmony_cioffset (``pos``) in the hardware buffer. When coded like memcpy-like 349162306a36Sopenharmony_ciway, the copy would look like:: 349262306a36Sopenharmony_ci 349362306a36Sopenharmony_ci my_memcpy_from_iter(my_buffer + pos, src, count); 349462306a36Sopenharmony_ci 349562306a36Sopenharmony_ciFor the capture direction, you copy the given amount of data (``count``) 349662306a36Sopenharmony_ciat the specified offset (``pos``) in the hardware buffer to the 349762306a36Sopenharmony_cispecified pointer (``dst``):: 349862306a36Sopenharmony_ci 349962306a36Sopenharmony_ci my_memcpy_to_iter(dst, my_buffer + pos, count); 350062306a36Sopenharmony_ci 350162306a36Sopenharmony_ciThe given ``src`` or ``dst`` a struct iov_iter pointer containing the 350262306a36Sopenharmony_cipointer and the size. Use the existing helpers to copy or access the 350362306a36Sopenharmony_cidata as defined in ``linux/uio.h``. 350462306a36Sopenharmony_ci 350562306a36Sopenharmony_ciCareful readers might notice that these callbacks receive the 350662306a36Sopenharmony_ciarguments in bytes, not in frames like other callbacks. It's because 350762306a36Sopenharmony_cithis makes coding easier like in the examples above, and also it makes 350862306a36Sopenharmony_ciit easier to unify both the interleaved and non-interleaved cases, as 350962306a36Sopenharmony_ciexplained below. 351062306a36Sopenharmony_ci 351162306a36Sopenharmony_ciIn the case of non-interleaved samples, the implementation will be a bit 351262306a36Sopenharmony_cimore complicated. The callback is called for each channel, passed in 351362306a36Sopenharmony_cithe second argument, so in total it's called N times per transfer. 351462306a36Sopenharmony_ci 351562306a36Sopenharmony_ciThe meaning of the other arguments are almost the same as in the 351662306a36Sopenharmony_ciinterleaved case. The callback is supposed to copy the data from/to 351762306a36Sopenharmony_cithe given user-space buffer, but only for the given channel. For 351862306a36Sopenharmony_cidetails, please check ``isa/gus/gus_pcm.c`` or ``pci/rme9652/rme9652.c`` 351962306a36Sopenharmony_cias examples. 352062306a36Sopenharmony_ci 352162306a36Sopenharmony_ciUsually for the playback, another callback ``fill_silence`` is 352262306a36Sopenharmony_cidefined. It's implemented in a similar way as the copy callbacks 352362306a36Sopenharmony_ciabove:: 352462306a36Sopenharmony_ci 352562306a36Sopenharmony_ci static int silence(struct snd_pcm_substream *substream, int channel, 352662306a36Sopenharmony_ci unsigned long pos, unsigned long count); 352762306a36Sopenharmony_ci 352862306a36Sopenharmony_ciThe meanings of arguments are the same as in the ``copy`` callback, 352962306a36Sopenharmony_cialthough there is no buffer pointer 353062306a36Sopenharmony_ciargument. In the case of interleaved samples, the channel argument has 353162306a36Sopenharmony_cino meaning, as for the ``copy`` callback. 353262306a36Sopenharmony_ci 353362306a36Sopenharmony_ciThe role of the ``fill_silence`` callback is to set the given amount 353462306a36Sopenharmony_ci(``count``) of silence data at the specified offset (``pos``) in the 353562306a36Sopenharmony_cihardware buffer. Suppose that the data format is signed (that is, the 353662306a36Sopenharmony_cisilent-data is 0), and the implementation using a memset-like function 353762306a36Sopenharmony_ciwould look like:: 353862306a36Sopenharmony_ci 353962306a36Sopenharmony_ci my_memset(my_buffer + pos, 0, count); 354062306a36Sopenharmony_ci 354162306a36Sopenharmony_ciIn the case of non-interleaved samples, again, the implementation 354262306a36Sopenharmony_cibecomes a bit more complicated, as it's called N times per transfer 354362306a36Sopenharmony_cifor each channel. See, for example, ``isa/gus/gus_pcm.c``. 354462306a36Sopenharmony_ci 354562306a36Sopenharmony_ciNon-Contiguous Buffers 354662306a36Sopenharmony_ci---------------------- 354762306a36Sopenharmony_ci 354862306a36Sopenharmony_ciIf your hardware supports a page table as in emu10k1 or buffer 354962306a36Sopenharmony_cidescriptors as in via82xx, you can use scatter-gather (SG) DMA. ALSA 355062306a36Sopenharmony_ciprovides an interface for handling SG-buffers. The API is provided in 355162306a36Sopenharmony_ci``<sound/pcm.h>``. 355262306a36Sopenharmony_ci 355362306a36Sopenharmony_ciFor creating the SG-buffer handler, call 355462306a36Sopenharmony_ci:c:func:`snd_pcm_set_managed_buffer()` or 355562306a36Sopenharmony_ci:c:func:`snd_pcm_set_managed_buffer_all()` with 355662306a36Sopenharmony_ci``SNDRV_DMA_TYPE_DEV_SG`` in the PCM constructor like for other PCI 355762306a36Sopenharmony_cipre-allocations. You need to pass ``&pci->dev``, where pci is 355862306a36Sopenharmony_cithe struct pci_dev pointer of the chip as well:: 355962306a36Sopenharmony_ci 356062306a36Sopenharmony_ci snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_DEV_SG, 356162306a36Sopenharmony_ci &pci->dev, size, max); 356262306a36Sopenharmony_ci 356362306a36Sopenharmony_ciThe ``struct snd_sg_buf`` instance is created as 356462306a36Sopenharmony_ci``substream->dma_private`` in turn. You can cast the pointer like:: 356562306a36Sopenharmony_ci 356662306a36Sopenharmony_ci struct snd_sg_buf *sgbuf = (struct snd_sg_buf *)substream->dma_private; 356762306a36Sopenharmony_ci 356862306a36Sopenharmony_ciThen in the :c:func:`snd_pcm_lib_malloc_pages()` call, the common SG-buffer 356962306a36Sopenharmony_cihandler will allocate the non-contiguous kernel pages of the given size 357062306a36Sopenharmony_ciand map them as virtually contiguous memory. The virtual pointer 357162306a36Sopenharmony_ciis addressed via runtime->dma_area. The physical address 357262306a36Sopenharmony_ci(``runtime->dma_addr``) is set to zero, because the buffer is 357362306a36Sopenharmony_ciphysically non-contiguous. The physical address table is set up in 357462306a36Sopenharmony_ci``sgbuf->table``. You can get the physical address at a certain offset 357562306a36Sopenharmony_civia :c:func:`snd_pcm_sgbuf_get_addr()`. 357662306a36Sopenharmony_ci 357762306a36Sopenharmony_ciIf you need to release the SG-buffer data explicitly, call the 357862306a36Sopenharmony_cistandard API function :c:func:`snd_pcm_lib_free_pages()` as usual. 357962306a36Sopenharmony_ci 358062306a36Sopenharmony_ciVmalloc'ed Buffers 358162306a36Sopenharmony_ci------------------ 358262306a36Sopenharmony_ci 358362306a36Sopenharmony_ciIt's possible to use a buffer allocated via :c:func:`vmalloc()`, for 358462306a36Sopenharmony_ciexample, for an intermediate buffer. 358562306a36Sopenharmony_ciYou can simply allocate it via the standard 358662306a36Sopenharmony_ci:c:func:`snd_pcm_lib_malloc_pages()` and co. after setting up the 358762306a36Sopenharmony_cibuffer preallocation with ``SNDRV_DMA_TYPE_VMALLOC`` type:: 358862306a36Sopenharmony_ci 358962306a36Sopenharmony_ci snd_pcm_set_managed_buffer_all(pcm, SNDRV_DMA_TYPE_VMALLOC, 359062306a36Sopenharmony_ci NULL, 0, 0); 359162306a36Sopenharmony_ci 359262306a36Sopenharmony_ciNULL is passed as the device pointer argument, which indicates 359362306a36Sopenharmony_cithat default pages (GFP_KERNEL and GFP_HIGHMEM) will be 359462306a36Sopenharmony_ciallocated. 359562306a36Sopenharmony_ci 359662306a36Sopenharmony_ciAlso, note that zero is passed as both the size and the max size 359762306a36Sopenharmony_ciargument here. Since each vmalloc call should succeed at any time, 359862306a36Sopenharmony_ciwe don't need to pre-allocate the buffers like other continuous 359962306a36Sopenharmony_cipages. 360062306a36Sopenharmony_ci 360162306a36Sopenharmony_ciProc Interface 360262306a36Sopenharmony_ci============== 360362306a36Sopenharmony_ci 360462306a36Sopenharmony_ciALSA provides an easy interface for procfs. The proc files are very 360562306a36Sopenharmony_ciuseful for debugging. I recommend you set up proc files if you write a 360662306a36Sopenharmony_cidriver and want to get a running status or register dumps. The API is 360762306a36Sopenharmony_cifound in ``<sound/info.h>``. 360862306a36Sopenharmony_ci 360962306a36Sopenharmony_ciTo create a proc file, call :c:func:`snd_card_proc_new()`:: 361062306a36Sopenharmony_ci 361162306a36Sopenharmony_ci struct snd_info_entry *entry; 361262306a36Sopenharmony_ci int err = snd_card_proc_new(card, "my-file", &entry); 361362306a36Sopenharmony_ci 361462306a36Sopenharmony_ciwhere the second argument specifies the name of the proc file to be 361562306a36Sopenharmony_cicreated. The above example will create a file ``my-file`` under the 361662306a36Sopenharmony_cicard directory, e.g. ``/proc/asound/card0/my-file``. 361762306a36Sopenharmony_ci 361862306a36Sopenharmony_ciLike other components, the proc entry created via 361962306a36Sopenharmony_ci:c:func:`snd_card_proc_new()` will be registered and released 362062306a36Sopenharmony_ciautomatically in the card registration and release functions. 362162306a36Sopenharmony_ci 362262306a36Sopenharmony_ciWhen the creation is successful, the function stores a new instance in 362362306a36Sopenharmony_cithe pointer given in the third argument. It is initialized as a text 362462306a36Sopenharmony_ciproc file for read only. To use this proc file as a read-only text file 362562306a36Sopenharmony_cias-is, set the read callback with private data via 362662306a36Sopenharmony_ci:c:func:`snd_info_set_text_ops()`:: 362762306a36Sopenharmony_ci 362862306a36Sopenharmony_ci snd_info_set_text_ops(entry, chip, my_proc_read); 362962306a36Sopenharmony_ci 363062306a36Sopenharmony_ciwhere the second argument (``chip``) is the private data to be used in 363162306a36Sopenharmony_cithe callback. The third parameter specifies the read buffer size and 363262306a36Sopenharmony_cithe fourth (``my_proc_read``) is the callback function, which is 363362306a36Sopenharmony_cidefined like:: 363462306a36Sopenharmony_ci 363562306a36Sopenharmony_ci static void my_proc_read(struct snd_info_entry *entry, 363662306a36Sopenharmony_ci struct snd_info_buffer *buffer); 363762306a36Sopenharmony_ci 363862306a36Sopenharmony_ciIn the read callback, use :c:func:`snd_iprintf()` for output 363962306a36Sopenharmony_cistrings, which works just like normal :c:func:`printf()`. For 364062306a36Sopenharmony_ciexample:: 364162306a36Sopenharmony_ci 364262306a36Sopenharmony_ci static void my_proc_read(struct snd_info_entry *entry, 364362306a36Sopenharmony_ci struct snd_info_buffer *buffer) 364462306a36Sopenharmony_ci { 364562306a36Sopenharmony_ci struct my_chip *chip = entry->private_data; 364662306a36Sopenharmony_ci 364762306a36Sopenharmony_ci snd_iprintf(buffer, "This is my chip!\n"); 364862306a36Sopenharmony_ci snd_iprintf(buffer, "Port = %ld\n", chip->port); 364962306a36Sopenharmony_ci } 365062306a36Sopenharmony_ci 365162306a36Sopenharmony_ciThe file permissions can be changed afterwards. By default, they are 365262306a36Sopenharmony_ciread only for all users. If you want to add write permission for the 365362306a36Sopenharmony_ciuser (root by default), do as follows:: 365462306a36Sopenharmony_ci 365562306a36Sopenharmony_ci entry->mode = S_IFREG | S_IRUGO | S_IWUSR; 365662306a36Sopenharmony_ci 365762306a36Sopenharmony_ciand set the write buffer size and the callback:: 365862306a36Sopenharmony_ci 365962306a36Sopenharmony_ci entry->c.text.write = my_proc_write; 366062306a36Sopenharmony_ci 366162306a36Sopenharmony_ciIn the write callback, you can use :c:func:`snd_info_get_line()` 366262306a36Sopenharmony_cito get a text line, and :c:func:`snd_info_get_str()` to retrieve 366362306a36Sopenharmony_cia string from the line. Some examples are found in 366462306a36Sopenharmony_ci``core/oss/mixer_oss.c``, core/oss/and ``pcm_oss.c``. 366562306a36Sopenharmony_ci 366662306a36Sopenharmony_ciFor a raw-data proc-file, set the attributes as follows:: 366762306a36Sopenharmony_ci 366862306a36Sopenharmony_ci static const struct snd_info_entry_ops my_file_io_ops = { 366962306a36Sopenharmony_ci .read = my_file_io_read, 367062306a36Sopenharmony_ci }; 367162306a36Sopenharmony_ci 367262306a36Sopenharmony_ci entry->content = SNDRV_INFO_CONTENT_DATA; 367362306a36Sopenharmony_ci entry->private_data = chip; 367462306a36Sopenharmony_ci entry->c.ops = &my_file_io_ops; 367562306a36Sopenharmony_ci entry->size = 4096; 367662306a36Sopenharmony_ci entry->mode = S_IFREG | S_IRUGO; 367762306a36Sopenharmony_ci 367862306a36Sopenharmony_ciFor raw data, ``size`` field must be set properly. This specifies 367962306a36Sopenharmony_cithe maximum size of the proc file access. 368062306a36Sopenharmony_ci 368162306a36Sopenharmony_ciThe read/write callbacks of raw mode are more direct than the text mode. 368262306a36Sopenharmony_ciYou need to use a low-level I/O functions such as 368362306a36Sopenharmony_ci:c:func:`copy_from_user()` and :c:func:`copy_to_user()` to transfer the 368462306a36Sopenharmony_cidata:: 368562306a36Sopenharmony_ci 368662306a36Sopenharmony_ci static ssize_t my_file_io_read(struct snd_info_entry *entry, 368762306a36Sopenharmony_ci void *file_private_data, 368862306a36Sopenharmony_ci struct file *file, 368962306a36Sopenharmony_ci char *buf, 369062306a36Sopenharmony_ci size_t count, 369162306a36Sopenharmony_ci loff_t pos) 369262306a36Sopenharmony_ci { 369362306a36Sopenharmony_ci if (copy_to_user(buf, local_data + pos, count)) 369462306a36Sopenharmony_ci return -EFAULT; 369562306a36Sopenharmony_ci return count; 369662306a36Sopenharmony_ci } 369762306a36Sopenharmony_ci 369862306a36Sopenharmony_ciIf the size of the info entry has been set up properly, ``count`` and 369962306a36Sopenharmony_ci``pos`` are guaranteed to fit within 0 and the given size. You don't 370062306a36Sopenharmony_cihave to check the range in the callbacks unless any other condition is 370162306a36Sopenharmony_cirequired. 370262306a36Sopenharmony_ci 370362306a36Sopenharmony_ciPower Management 370462306a36Sopenharmony_ci================ 370562306a36Sopenharmony_ci 370662306a36Sopenharmony_ciIf the chip is supposed to work with suspend/resume functions, you need 370762306a36Sopenharmony_cito add power-management code to the driver. The additional code for 370862306a36Sopenharmony_cipower-management should be ifdef-ed with ``CONFIG_PM``, or annotated 370962306a36Sopenharmony_ciwith __maybe_unused attribute; otherwise the compiler will complain. 371062306a36Sopenharmony_ci 371162306a36Sopenharmony_ciIf the driver *fully* supports suspend/resume that is, the device can be 371262306a36Sopenharmony_ciproperly resumed to its state when suspend was called, you can set the 371362306a36Sopenharmony_ci``SNDRV_PCM_INFO_RESUME`` flag in the PCM info field. Usually, this is 371462306a36Sopenharmony_cipossible when the registers of the chip can be safely saved and restored 371562306a36Sopenharmony_cito RAM. If this is set, the trigger callback is called with 371662306a36Sopenharmony_ci``SNDRV_PCM_TRIGGER_RESUME`` after the resume callback completes. 371762306a36Sopenharmony_ci 371862306a36Sopenharmony_ciEven if the driver doesn't support PM fully but partial suspend/resume 371962306a36Sopenharmony_ciis still possible, it's still worthy to implement suspend/resume 372062306a36Sopenharmony_cicallbacks. In such a case, applications would reset the status by 372162306a36Sopenharmony_cicalling :c:func:`snd_pcm_prepare()` and restart the stream 372262306a36Sopenharmony_ciappropriately. Hence, you can define suspend/resume callbacks below but 372362306a36Sopenharmony_cidon't set the ``SNDRV_PCM_INFO_RESUME`` info flag to the PCM. 372462306a36Sopenharmony_ci 372562306a36Sopenharmony_ciNote that the trigger with SUSPEND can always be called when 372662306a36Sopenharmony_ci:c:func:`snd_pcm_suspend_all()` is called, regardless of the 372762306a36Sopenharmony_ci``SNDRV_PCM_INFO_RESUME`` flag. The ``RESUME`` flag affects only the 372862306a36Sopenharmony_cibehavior of :c:func:`snd_pcm_resume()`. (Thus, in theory, 372962306a36Sopenharmony_ci``SNDRV_PCM_TRIGGER_RESUME`` isn't needed to be handled in the trigger 373062306a36Sopenharmony_cicallback when no ``SNDRV_PCM_INFO_RESUME`` flag is set. But, it's better 373162306a36Sopenharmony_cito keep it for compatibility reasons.) 373262306a36Sopenharmony_ci 373362306a36Sopenharmony_ciThe driver needs to define the 373462306a36Sopenharmony_cisuspend/resume hooks according to the bus the device is connected to. In 373562306a36Sopenharmony_cithe case of PCI drivers, the callbacks look like below:: 373662306a36Sopenharmony_ci 373762306a36Sopenharmony_ci static int __maybe_unused snd_my_suspend(struct device *dev) 373862306a36Sopenharmony_ci { 373962306a36Sopenharmony_ci .... /* do things for suspend */ 374062306a36Sopenharmony_ci return 0; 374162306a36Sopenharmony_ci } 374262306a36Sopenharmony_ci static int __maybe_unused snd_my_resume(struct device *dev) 374362306a36Sopenharmony_ci { 374462306a36Sopenharmony_ci .... /* do things for suspend */ 374562306a36Sopenharmony_ci return 0; 374662306a36Sopenharmony_ci } 374762306a36Sopenharmony_ci 374862306a36Sopenharmony_ciThe scheme of the real suspend job is as follows: 374962306a36Sopenharmony_ci 375062306a36Sopenharmony_ci1. Retrieve the card and the chip data. 375162306a36Sopenharmony_ci 375262306a36Sopenharmony_ci2. Call :c:func:`snd_power_change_state()` with 375362306a36Sopenharmony_ci ``SNDRV_CTL_POWER_D3hot`` to change the power status. 375462306a36Sopenharmony_ci 375562306a36Sopenharmony_ci3. If AC97 codecs are used, call :c:func:`snd_ac97_suspend()` for 375662306a36Sopenharmony_ci each codec. 375762306a36Sopenharmony_ci 375862306a36Sopenharmony_ci4. Save the register values if necessary. 375962306a36Sopenharmony_ci 376062306a36Sopenharmony_ci5. Stop the hardware if necessary. 376162306a36Sopenharmony_ci 376262306a36Sopenharmony_ciTypical code would look like:: 376362306a36Sopenharmony_ci 376462306a36Sopenharmony_ci static int __maybe_unused mychip_suspend(struct device *dev) 376562306a36Sopenharmony_ci { 376662306a36Sopenharmony_ci /* (1) */ 376762306a36Sopenharmony_ci struct snd_card *card = dev_get_drvdata(dev); 376862306a36Sopenharmony_ci struct mychip *chip = card->private_data; 376962306a36Sopenharmony_ci /* (2) */ 377062306a36Sopenharmony_ci snd_power_change_state(card, SNDRV_CTL_POWER_D3hot); 377162306a36Sopenharmony_ci /* (3) */ 377262306a36Sopenharmony_ci snd_ac97_suspend(chip->ac97); 377362306a36Sopenharmony_ci /* (4) */ 377462306a36Sopenharmony_ci snd_mychip_save_registers(chip); 377562306a36Sopenharmony_ci /* (5) */ 377662306a36Sopenharmony_ci snd_mychip_stop_hardware(chip); 377762306a36Sopenharmony_ci return 0; 377862306a36Sopenharmony_ci } 377962306a36Sopenharmony_ci 378062306a36Sopenharmony_ci 378162306a36Sopenharmony_ciThe scheme of the real resume job is as follows: 378262306a36Sopenharmony_ci 378362306a36Sopenharmony_ci1. Retrieve the card and the chip data. 378462306a36Sopenharmony_ci 378562306a36Sopenharmony_ci2. Re-initialize the chip. 378662306a36Sopenharmony_ci 378762306a36Sopenharmony_ci3. Restore the saved registers if necessary. 378862306a36Sopenharmony_ci 378962306a36Sopenharmony_ci4. Resume the mixer, e.g. by calling :c:func:`snd_ac97_resume()`. 379062306a36Sopenharmony_ci 379162306a36Sopenharmony_ci5. Restart the hardware (if any). 379262306a36Sopenharmony_ci 379362306a36Sopenharmony_ci6. Call :c:func:`snd_power_change_state()` with 379462306a36Sopenharmony_ci ``SNDRV_CTL_POWER_D0`` to notify the processes. 379562306a36Sopenharmony_ci 379662306a36Sopenharmony_ciTypical code would look like:: 379762306a36Sopenharmony_ci 379862306a36Sopenharmony_ci static int __maybe_unused mychip_resume(struct pci_dev *pci) 379962306a36Sopenharmony_ci { 380062306a36Sopenharmony_ci /* (1) */ 380162306a36Sopenharmony_ci struct snd_card *card = dev_get_drvdata(dev); 380262306a36Sopenharmony_ci struct mychip *chip = card->private_data; 380362306a36Sopenharmony_ci /* (2) */ 380462306a36Sopenharmony_ci snd_mychip_reinit_chip(chip); 380562306a36Sopenharmony_ci /* (3) */ 380662306a36Sopenharmony_ci snd_mychip_restore_registers(chip); 380762306a36Sopenharmony_ci /* (4) */ 380862306a36Sopenharmony_ci snd_ac97_resume(chip->ac97); 380962306a36Sopenharmony_ci /* (5) */ 381062306a36Sopenharmony_ci snd_mychip_restart_chip(chip); 381162306a36Sopenharmony_ci /* (6) */ 381262306a36Sopenharmony_ci snd_power_change_state(card, SNDRV_CTL_POWER_D0); 381362306a36Sopenharmony_ci return 0; 381462306a36Sopenharmony_ci } 381562306a36Sopenharmony_ci 381662306a36Sopenharmony_ciNote that, at the time this callback gets called, the PCM stream has 381762306a36Sopenharmony_cibeen already suspended via its own PM ops calling 381862306a36Sopenharmony_ci:c:func:`snd_pcm_suspend_all()` internally. 381962306a36Sopenharmony_ci 382062306a36Sopenharmony_ciOK, we have all callbacks now. Let's set them up. In the initialization 382162306a36Sopenharmony_ciof the card, make sure that you can get the chip data from the card 382262306a36Sopenharmony_ciinstance, typically via ``private_data`` field, in case you created the 382362306a36Sopenharmony_cichip data individually:: 382462306a36Sopenharmony_ci 382562306a36Sopenharmony_ci static int snd_mychip_probe(struct pci_dev *pci, 382662306a36Sopenharmony_ci const struct pci_device_id *pci_id) 382762306a36Sopenharmony_ci { 382862306a36Sopenharmony_ci .... 382962306a36Sopenharmony_ci struct snd_card *card; 383062306a36Sopenharmony_ci struct mychip *chip; 383162306a36Sopenharmony_ci int err; 383262306a36Sopenharmony_ci .... 383362306a36Sopenharmony_ci err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, 383462306a36Sopenharmony_ci 0, &card); 383562306a36Sopenharmony_ci .... 383662306a36Sopenharmony_ci chip = kzalloc(sizeof(*chip), GFP_KERNEL); 383762306a36Sopenharmony_ci .... 383862306a36Sopenharmony_ci card->private_data = chip; 383962306a36Sopenharmony_ci .... 384062306a36Sopenharmony_ci } 384162306a36Sopenharmony_ci 384262306a36Sopenharmony_ciWhen you created the chip data with :c:func:`snd_card_new()`, it's 384362306a36Sopenharmony_cianyway accessible via ``private_data`` field:: 384462306a36Sopenharmony_ci 384562306a36Sopenharmony_ci static int snd_mychip_probe(struct pci_dev *pci, 384662306a36Sopenharmony_ci const struct pci_device_id *pci_id) 384762306a36Sopenharmony_ci { 384862306a36Sopenharmony_ci .... 384962306a36Sopenharmony_ci struct snd_card *card; 385062306a36Sopenharmony_ci struct mychip *chip; 385162306a36Sopenharmony_ci int err; 385262306a36Sopenharmony_ci .... 385362306a36Sopenharmony_ci err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE, 385462306a36Sopenharmony_ci sizeof(struct mychip), &card); 385562306a36Sopenharmony_ci .... 385662306a36Sopenharmony_ci chip = card->private_data; 385762306a36Sopenharmony_ci .... 385862306a36Sopenharmony_ci } 385962306a36Sopenharmony_ci 386062306a36Sopenharmony_ciIf you need space to save the registers, allocate the buffer for it 386162306a36Sopenharmony_cihere, too, since it would be fatal if you cannot allocate a memory in 386262306a36Sopenharmony_cithe suspend phase. The allocated buffer should be released in the 386362306a36Sopenharmony_cicorresponding destructor. 386462306a36Sopenharmony_ci 386562306a36Sopenharmony_ciAnd next, set suspend/resume callbacks to the pci_driver:: 386662306a36Sopenharmony_ci 386762306a36Sopenharmony_ci static SIMPLE_DEV_PM_OPS(snd_my_pm_ops, mychip_suspend, mychip_resume); 386862306a36Sopenharmony_ci 386962306a36Sopenharmony_ci static struct pci_driver driver = { 387062306a36Sopenharmony_ci .name = KBUILD_MODNAME, 387162306a36Sopenharmony_ci .id_table = snd_my_ids, 387262306a36Sopenharmony_ci .probe = snd_my_probe, 387362306a36Sopenharmony_ci .remove = snd_my_remove, 387462306a36Sopenharmony_ci .driver.pm = &snd_my_pm_ops, 387562306a36Sopenharmony_ci }; 387662306a36Sopenharmony_ci 387762306a36Sopenharmony_ciModule Parameters 387862306a36Sopenharmony_ci================= 387962306a36Sopenharmony_ci 388062306a36Sopenharmony_ciThere are standard module options for ALSA. At least, each module should 388162306a36Sopenharmony_cihave the ``index``, ``id`` and ``enable`` options. 388262306a36Sopenharmony_ci 388362306a36Sopenharmony_ciIf the module supports multiple cards (usually up to 8 = ``SNDRV_CARDS`` 388462306a36Sopenharmony_cicards), they should be arrays. The default initial values are defined 388562306a36Sopenharmony_cialready as constants for easier programming:: 388662306a36Sopenharmony_ci 388762306a36Sopenharmony_ci static int index[SNDRV_CARDS] = SNDRV_DEFAULT_IDX; 388862306a36Sopenharmony_ci static char *id[SNDRV_CARDS] = SNDRV_DEFAULT_STR; 388962306a36Sopenharmony_ci static int enable[SNDRV_CARDS] = SNDRV_DEFAULT_ENABLE_PNP; 389062306a36Sopenharmony_ci 389162306a36Sopenharmony_ciIf the module supports only a single card, they could be single 389262306a36Sopenharmony_civariables, instead. ``enable`` option is not always necessary in this 389362306a36Sopenharmony_cicase, but it would be better to have a dummy option for compatibility. 389462306a36Sopenharmony_ci 389562306a36Sopenharmony_ciThe module parameters must be declared with the standard 389662306a36Sopenharmony_ci``module_param()``, ``module_param_array()`` and 389762306a36Sopenharmony_ci:c:func:`MODULE_PARM_DESC()` macros. 389862306a36Sopenharmony_ci 389962306a36Sopenharmony_ciTypical code would look as below:: 390062306a36Sopenharmony_ci 390162306a36Sopenharmony_ci #define CARD_NAME "My Chip" 390262306a36Sopenharmony_ci 390362306a36Sopenharmony_ci module_param_array(index, int, NULL, 0444); 390462306a36Sopenharmony_ci MODULE_PARM_DESC(index, "Index value for " CARD_NAME " soundcard."); 390562306a36Sopenharmony_ci module_param_array(id, charp, NULL, 0444); 390662306a36Sopenharmony_ci MODULE_PARM_DESC(id, "ID string for " CARD_NAME " soundcard."); 390762306a36Sopenharmony_ci module_param_array(enable, bool, NULL, 0444); 390862306a36Sopenharmony_ci MODULE_PARM_DESC(enable, "Enable " CARD_NAME " soundcard."); 390962306a36Sopenharmony_ci 391062306a36Sopenharmony_ciAlso, don't forget to define the module description and the license. 391162306a36Sopenharmony_ciEspecially, the recent modprobe requires to define the 391262306a36Sopenharmony_cimodule license as GPL, etc., otherwise the system is shown as “tainted”:: 391362306a36Sopenharmony_ci 391462306a36Sopenharmony_ci MODULE_DESCRIPTION("Sound driver for My Chip"); 391562306a36Sopenharmony_ci MODULE_LICENSE("GPL"); 391662306a36Sopenharmony_ci 391762306a36Sopenharmony_ci 391862306a36Sopenharmony_ciDevice-Managed Resources 391962306a36Sopenharmony_ci======================== 392062306a36Sopenharmony_ci 392162306a36Sopenharmony_ciIn the examples above, all resources are allocated and released 392262306a36Sopenharmony_cimanually. But human beings are lazy in nature, especially developers 392362306a36Sopenharmony_ciare lazier. So there are some ways to automate the release part; it's 392462306a36Sopenharmony_cithe (device-)managed resources aka devres or devm family. For 392562306a36Sopenharmony_ciexample, an object allocated via :c:func:`devm_kmalloc()` will be 392662306a36Sopenharmony_cifreed automatically at unbinding the device. 392762306a36Sopenharmony_ci 392862306a36Sopenharmony_ciALSA core provides also the device-managed helper, namely, 392962306a36Sopenharmony_ci:c:func:`snd_devm_card_new()` for creating a card object. 393062306a36Sopenharmony_ciCall this functions instead of the normal :c:func:`snd_card_new()`, 393162306a36Sopenharmony_ciand you can forget the explicit :c:func:`snd_card_free()` call, as 393262306a36Sopenharmony_ciit's called automagically at error and removal paths. 393362306a36Sopenharmony_ci 393462306a36Sopenharmony_ciOne caveat is that the call of :c:func:`snd_card_free()` would be put 393562306a36Sopenharmony_ciat the beginning of the call chain only after you call 393662306a36Sopenharmony_ci:c:func:`snd_card_register()`. 393762306a36Sopenharmony_ci 393862306a36Sopenharmony_ciAlso, the ``private_free`` callback is always called at the card free, 393962306a36Sopenharmony_ciso be careful to put the hardware clean-up procedure in 394062306a36Sopenharmony_ci``private_free`` callback. It might be called even before you 394162306a36Sopenharmony_ciactually set up at an earlier error path. For avoiding such an 394262306a36Sopenharmony_ciinvalid initialization, you can set ``private_free`` callback after 394362306a36Sopenharmony_ci:c:func:`snd_card_register()` call succeeds. 394462306a36Sopenharmony_ci 394562306a36Sopenharmony_ciAnother thing to be remarked is that you should use device-managed 394662306a36Sopenharmony_cihelpers for each component as much as possible once when you manage 394762306a36Sopenharmony_cithe card in that way. Mixing up with the normal and the managed 394862306a36Sopenharmony_ciresources may screw up the release order. 394962306a36Sopenharmony_ci 395062306a36Sopenharmony_ci 395162306a36Sopenharmony_ciHow To Put Your Driver Into ALSA Tree 395262306a36Sopenharmony_ci===================================== 395362306a36Sopenharmony_ci 395462306a36Sopenharmony_ciGeneral 395562306a36Sopenharmony_ci------- 395662306a36Sopenharmony_ci 395762306a36Sopenharmony_ciSo far, you've learned how to write the driver codes. And you might have 395862306a36Sopenharmony_cia question now: how to put my own driver into the ALSA driver tree? Here 395962306a36Sopenharmony_ci(finally :) the standard procedure is described briefly. 396062306a36Sopenharmony_ci 396162306a36Sopenharmony_ciSuppose that you create a new PCI driver for the card “xyz”. The card 396262306a36Sopenharmony_cimodule name would be snd-xyz. The new driver is usually put into the 396362306a36Sopenharmony_cialsa-driver tree, ``sound/pci`` directory in the case of PCI 396462306a36Sopenharmony_cicards. 396562306a36Sopenharmony_ci 396662306a36Sopenharmony_ciIn the following sections, the driver code is supposed to be put into 396762306a36Sopenharmony_ciLinux kernel tree. The two cases are covered: a driver consisting of a 396862306a36Sopenharmony_cisingle source file and one consisting of several source files. 396962306a36Sopenharmony_ci 397062306a36Sopenharmony_ciDriver with A Single Source File 397162306a36Sopenharmony_ci-------------------------------- 397262306a36Sopenharmony_ci 397362306a36Sopenharmony_ci1. Modify sound/pci/Makefile 397462306a36Sopenharmony_ci 397562306a36Sopenharmony_ci Suppose you have a file xyz.c. Add the following two lines:: 397662306a36Sopenharmony_ci 397762306a36Sopenharmony_ci snd-xyz-objs := xyz.o 397862306a36Sopenharmony_ci obj-$(CONFIG_SND_XYZ) += snd-xyz.o 397962306a36Sopenharmony_ci 398062306a36Sopenharmony_ci2. Create the Kconfig entry 398162306a36Sopenharmony_ci 398262306a36Sopenharmony_ci Add the new entry of Kconfig for your xyz driver:: 398362306a36Sopenharmony_ci 398462306a36Sopenharmony_ci config SND_XYZ 398562306a36Sopenharmony_ci tristate "Foobar XYZ" 398662306a36Sopenharmony_ci depends on SND 398762306a36Sopenharmony_ci select SND_PCM 398862306a36Sopenharmony_ci help 398962306a36Sopenharmony_ci Say Y here to include support for Foobar XYZ soundcard. 399062306a36Sopenharmony_ci To compile this driver as a module, choose M here: 399162306a36Sopenharmony_ci the module will be called snd-xyz. 399262306a36Sopenharmony_ci 399362306a36Sopenharmony_ciThe line ``select SND_PCM`` specifies that the driver xyz supports PCM. 399462306a36Sopenharmony_ciIn addition to SND_PCM, the following components are supported for 399562306a36Sopenharmony_ciselect command: SND_RAWMIDI, SND_TIMER, SND_HWDEP, SND_MPU401_UART, 399662306a36Sopenharmony_ciSND_OPL3_LIB, SND_OPL4_LIB, SND_VX_LIB, SND_AC97_CODEC. 399762306a36Sopenharmony_ciAdd the select command for each supported component. 399862306a36Sopenharmony_ci 399962306a36Sopenharmony_ciNote that some selections imply the lowlevel selections. For example, 400062306a36Sopenharmony_ciPCM includes TIMER, MPU401_UART includes RAWMIDI, AC97_CODEC 400162306a36Sopenharmony_ciincludes PCM, and OPL3_LIB includes HWDEP. You don't need to give 400262306a36Sopenharmony_cithe lowlevel selections again. 400362306a36Sopenharmony_ci 400462306a36Sopenharmony_ciFor the details of Kconfig script, refer to the kbuild documentation. 400562306a36Sopenharmony_ci 400662306a36Sopenharmony_ciDrivers with Several Source Files 400762306a36Sopenharmony_ci--------------------------------- 400862306a36Sopenharmony_ci 400962306a36Sopenharmony_ciSuppose that the driver snd-xyz have several source files. They are 401062306a36Sopenharmony_cilocated in the new subdirectory, sound/pci/xyz. 401162306a36Sopenharmony_ci 401262306a36Sopenharmony_ci1. Add a new directory (``sound/pci/xyz``) in ``sound/pci/Makefile`` 401362306a36Sopenharmony_ci as below:: 401462306a36Sopenharmony_ci 401562306a36Sopenharmony_ci obj-$(CONFIG_SND) += sound/pci/xyz/ 401662306a36Sopenharmony_ci 401762306a36Sopenharmony_ci 401862306a36Sopenharmony_ci2. Under the directory ``sound/pci/xyz``, create a Makefile:: 401962306a36Sopenharmony_ci 402062306a36Sopenharmony_ci snd-xyz-objs := xyz.o abc.o def.o 402162306a36Sopenharmony_ci obj-$(CONFIG_SND_XYZ) += snd-xyz.o 402262306a36Sopenharmony_ci 402362306a36Sopenharmony_ci3. Create the Kconfig entry 402462306a36Sopenharmony_ci 402562306a36Sopenharmony_ci This procedure is as same as in the last section. 402662306a36Sopenharmony_ci 402762306a36Sopenharmony_ci 402862306a36Sopenharmony_ciUseful Functions 402962306a36Sopenharmony_ci================ 403062306a36Sopenharmony_ci 403162306a36Sopenharmony_ci:c:func:`snd_printk()` and friends 403262306a36Sopenharmony_ci---------------------------------- 403362306a36Sopenharmony_ci 403462306a36Sopenharmony_ci.. note:: This subsection describes a few helper functions for 403562306a36Sopenharmony_ci decorating a bit more on the standard :c:func:`printk()` & co. 403662306a36Sopenharmony_ci However, in general, the use of such helpers is no longer recommended. 403762306a36Sopenharmony_ci If possible, try to stick with the standard functions like 403862306a36Sopenharmony_ci :c:func:`dev_err()` or :c:func:`pr_err()`. 403962306a36Sopenharmony_ci 404062306a36Sopenharmony_ciALSA provides a verbose version of the :c:func:`printk()` function. 404162306a36Sopenharmony_ciIf a kernel config ``CONFIG_SND_VERBOSE_PRINTK`` is set, this function 404262306a36Sopenharmony_ciprints the given message together with the file name and the line of the 404362306a36Sopenharmony_cicaller. The ``KERN_XXX`` prefix is processed as well as the original 404462306a36Sopenharmony_ci:c:func:`printk()` does, so it's recommended to add this prefix, 404562306a36Sopenharmony_cie.g. snd_printk(KERN_ERR "Oh my, sorry, it's extremely bad!\\n"); 404662306a36Sopenharmony_ci 404762306a36Sopenharmony_ciThere are also :c:func:`printk()`'s for debugging. 404862306a36Sopenharmony_ci:c:func:`snd_printd()` can be used for general debugging purposes. 404962306a36Sopenharmony_ciIf ``CONFIG_SND_DEBUG`` is set, this function is compiled, and works 405062306a36Sopenharmony_cijust like :c:func:`snd_printk()`. If the ALSA is compiled without 405162306a36Sopenharmony_cithe debugging flag, it's ignored. 405262306a36Sopenharmony_ci 405362306a36Sopenharmony_ci:c:func:`snd_printdd()` is compiled in only when 405462306a36Sopenharmony_ci``CONFIG_SND_DEBUG_VERBOSE`` is set. 405562306a36Sopenharmony_ci 405662306a36Sopenharmony_ci:c:func:`snd_BUG()` 405762306a36Sopenharmony_ci------------------- 405862306a36Sopenharmony_ci 405962306a36Sopenharmony_ciIt shows the ``BUG?`` message and stack trace as well as 406062306a36Sopenharmony_ci:c:func:`snd_BUG_ON()` at the point. It's useful to show that a 406162306a36Sopenharmony_cifatal error happens there. 406262306a36Sopenharmony_ci 406362306a36Sopenharmony_ciWhen no debug flag is set, this macro is ignored. 406462306a36Sopenharmony_ci 406562306a36Sopenharmony_ci:c:func:`snd_BUG_ON()` 406662306a36Sopenharmony_ci---------------------- 406762306a36Sopenharmony_ci 406862306a36Sopenharmony_ci:c:func:`snd_BUG_ON()` macro is similar with 406962306a36Sopenharmony_ci:c:func:`WARN_ON()` macro. For example, snd_BUG_ON(!pointer); or 407062306a36Sopenharmony_ciit can be used as the condition, if (snd_BUG_ON(non_zero_is_bug)) 407162306a36Sopenharmony_cireturn -EINVAL; 407262306a36Sopenharmony_ci 407362306a36Sopenharmony_ciThe macro takes an conditional expression to evaluate. When 407462306a36Sopenharmony_ci``CONFIG_SND_DEBUG``, is set, if the expression is non-zero, it shows 407562306a36Sopenharmony_cithe warning message such as ``BUG? (xxx)`` normally followed by stack 407662306a36Sopenharmony_citrace. In both cases it returns the evaluated value. 407762306a36Sopenharmony_ci 407862306a36Sopenharmony_ciAcknowledgments 407962306a36Sopenharmony_ci=============== 408062306a36Sopenharmony_ci 408162306a36Sopenharmony_ciI would like to thank Phil Kerr for his help for improvement and 408262306a36Sopenharmony_cicorrections of this document. 408362306a36Sopenharmony_ci 408462306a36Sopenharmony_ciKevin Conder reformatted the original plain-text to the DocBook format. 408562306a36Sopenharmony_ci 408662306a36Sopenharmony_ciGiuliano Pochini corrected typos and contributed the example codes in 408762306a36Sopenharmony_cithe hardware constraints section. 4088