Linux Sound Subsystem Documentation Release 4.13.0-Rc4+
Total Page:16
File Type:pdf, Size:1020Kb
Linux Sound Subsystem Documentation Release 4.13.0-rc4+ The kernel development community Sep 05, 2017 CONTENTS 1 ALSA Kernel API Documentation 1 1.1 The ALSA Driver API ............................................ 1 1.2 Writing an ALSA Driver ........................................... 89 2 Designs and Implementations 145 2.1 Standard ALSA Control Names ...................................... 145 2.2 ALSA PCM channel-mapping API ..................................... 147 2.3 ALSA Compress-Offload API ........................................ 149 2.4 ALSA PCM Timestamping ......................................... 152 2.5 ALSA Jack Controls ............................................. 155 2.6 Tracepoints in ALSA ............................................ 156 2.7 Proc Files of ALSA Drivers ......................................... 158 2.8 Notes on Power-Saving Mode ....................................... 161 2.9 Notes on Kernel OSS-Emulation ..................................... 161 2.10 OSS Sequencer Emulation on ALSA ................................... 165 3 ALSA SoC Layer 171 3.1 ALSA SoC Layer Overview ......................................... 171 3.2 ASoC Codec Class Driver ......................................... 172 3.3 ASoC Digital Audio Interface (DAI) .................................... 174 3.4 Dynamic Audio Power Management for Portable Devices ...................... 175 3.5 ASoC Platform Driver ............................................ 180 3.6 ASoC Machine Driver ............................................ 181 3.7 Audio Pops and Clicks ........................................... 183 3.8 Audio Clocking ............................................... 184 3.9 ASoC jack detection ............................................ 184 3.10 Dynamic PCM ................................................ 185 3.11 Creating codec to codec dai link for ALSA dapm ........................... 191 4 Advanced Linux Sound Architecture - Driver Configuration guide 193 4.1 Kernel Configuration ............................................ 193 4.2 Module parameters ............................................. 193 4.3 AC97 Quirk Option ............................................. 225 4.4 Configuring Non-ISAPNP Cards ...................................... 225 4.5 Module Autoloading Support ....................................... 225 4.6 ALSA PCM devices to OSS devices mapping .............................. 226 4.7 Proc interfaces (/proc/asound) ...................................... 227 4.8 Early Buffer Allocation ........................................... 227 4.9 Links and Addresses ............................................ 228 5 HD-Audio 229 5.1 More Notes on HD-Audio Driver ..................................... 229 5.2 HD-Audio Codec-Specific Models ..................................... 240 5.3 HD-Audio Codec-Specific Mixer Controls ................................ 247 5.4 HD-Audio DP-MST Support ........................................ 249 i 6 Card-Specific Information 251 6.1 Analog Joystick Support on ALSA Drivers ................................ 251 6.2 Brief Notes on C-Media 8338/8738/8768/8770 Driver ........................ 252 6.3 Sound Blaster Live mixer / default DSP code .............................. 255 6.4 Sound Blaster Audigy mixer / default DSP code ............................ 261 6.5 Low latency, multichannel audio with JACK and the emu10k1/emu10k2 ............. 267 6.6 VIA82xx mixer ................................................ 268 6.7 Guide to using M-Audio Audiophile USB with ALSA and Jack .................... 269 6.8 Alsa driver for Digigram miXart8 and miXart8AES/EBU soundcards ................ 277 6.9 ALSA BT87x Driver ............................................. 278 6.10 Notes on Maya44 USB Audio Support .................................. 279 6.11 Software Interface ALSA-DSP MADI Driver ............................... 282 6.12 Serial UART 16450/16550 MIDI driver .................................. 287 6.13 Imagination Technologies SPDIF Input Controllers .......................... 289 Index 291 ii CHAPTER ONE ALSA KERNEL API DOCUMENTATION 1.1 The ALSA Driver API 1.1.1 Management of Cards and Devices Card Management void snd_device_initialize(struct device * dev, struct snd_card * card) Initialize struct device for sound devices Parameters struct device * dev device to initialize struct snd_card * card card to assign, optional int snd_card_new(struct device * parent, int idx, const char * xid, struct module * module, int extra_size, struct snd_card ** card_ret) create and initialize a soundcard structure Parameters struct device * parent the parent device object int idx card index (address) [0 ... (SNDRV_CARDS-1)] const char * xid card identification (ASCII string) struct module * module top level module for locking int extra_size allocate this extra size after the main soundcard structure struct snd_card ** card_ret the pointer to store the created card instance Description Creates and initializes a soundcard structure. The function allocates snd_card instance via kzalloc with the given space for the driver to use freely. The allocated struct is stored in the given card_ret pointer. Return Zero if successful or a negative error code. int snd_card_disconnect(struct snd_card * card) disconnect all APIs from the file-operations (user space) Parameters struct snd_card * card soundcard structure Description Disconnects all APIs from the file-operations (user space). 1 Linux Sound Subsystem Documentation, Release 4.13.0-rc4+ Return Zero, otherwise a negative error code. Note The current implementation replaces all active file->f_op with special dummy file operations (they do nothing except release). int snd_card_free_when_closed(struct snd_card * card) Disconnect the card, free it later eventually Parameters struct snd_card * card soundcard structure Description Unlike snd_card_free(), this function doesn’t try to release the card resource immediately, but tries to disconnect at first. When the card is still in use, the function returns before freeing the resources. The card resources will be freed when the refcount gets to zero. int snd_card_free(struct snd_card * card) frees given soundcard structure Parameters struct snd_card * card soundcard structure Description This function releases the soundcard structure and the all assigned devices automatically. That is, you don’t have to release the devices by yourself. This function waits until the all resources are properly released. Return Zero. Frees all associated devices and frees the control interface associated to given soundcard. void snd_card_set_id(struct snd_card * card, const char * nid) set card identification name Parameters struct snd_card * card soundcard structure const char * nid new identification string Description This function sets the card identification and checks for name collisions. int snd_card_add_dev_attr(struct snd_card * card, const struct attribute_group * group) Append a new sysfs attribute group to card Parameters struct snd_card * card card instance const struct attribute_group * group attribute group to append int snd_card_register(struct snd_card * card) register the soundcard Parameters struct snd_card * card soundcard structure Description This function registers all the devices assigned to the soundcard. Until calling this, the ALSA control interface is blocked from the external accesses. Thus, you should call this function at the end of the initialization of the card. 2 Chapter 1. ALSA Kernel API Documentation Linux Sound Subsystem Documentation, Release 4.13.0-rc4+ Return Zero otherwise a negative error code if the registration failed. int snd_component_add(struct snd_card * card, const char * component) add a component string Parameters struct snd_card * card soundcard structure const char * component the component id string Description This function adds the component id string to the supported list. The component can be referred from the alsa-lib. Return Zero otherwise a negative error code. int snd_card_file_add(struct snd_card * card, struct file * file) add the file to the file list of the card Parameters struct snd_card * card soundcard structure struct file * file file pointer Description This function adds the file to the file linked-list of the card. This linked-list is used to keep tracking the connection state, and to avoid the release of busy resources by hotplug. Return zero or a negative error code. int snd_card_file_remove(struct snd_card * card, struct file * file) remove the file from the file list Parameters struct snd_card * card soundcard structure struct file * file file pointer Description This function removes the file formerly added to the card via snd_card_file_add() function. If all files are removed and snd_card_free_when_closed() was called beforehand, it processes the pending release of resources. Return Zero or a negative error code. int snd_power_wait(struct snd_card * card, unsigned int power_state) wait until the power-state is changed. Parameters struct snd_card * card soundcard structure unsigned int power_state expected power state Description Waits until the power-state is changed. 1.1. The ALSA Driver API 3 Linux Sound Subsystem Documentation, Release 4.13.0-rc4+ Return Zero if successful, or a negative error code. Note the power lock must be active before call. Device Components int snd_device_new(struct snd_card * card, enum snd_device_type type, void * device_data, struct snd_device_ops * ops) create an ALSA device component Parameters struct snd_card * card the card instance enum snd_device_type type the