The ALSA Driver API i

The ALSA Driver API

The ALSA Driver API ii
This document is free; you can redistribute it and/or modify it under the terms of the GNU General Public License as published
by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This document is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
The ALSA Driver API iii
COLLABORATORS
TITLE :
The ALSA Driver API
ACTION NAME DATE SIGNATURE
WRITTEN BY July 31, 2014
REVISION HISTORY
NUMBER DATE DESCRIPTION NAME
The ALSA Driver API iv
Contents
1 Management of Cards and Devices 1
1.1 Card Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1.1 snd_card_new . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1.2 snd_card_disconnect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.1.3 snd_card_set_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.4 snd_card_register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.5 snd_component_add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.6 snd_card_le_add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.7 snd_card_le_remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1.8 snd_power_wait . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2 Device Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2.1 snd_device_new . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2.2 snd_device_free . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2.3 snd_device_register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.3 Module requests and Device File Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.3.1 snd_request_card . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.3.2 snd_lookup_minor_data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.3.3 snd_register_device_for_dev . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3.4 snd_unregister_device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.4 Memory Management Helpers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.4.1 copy_to_user_fromio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.4.2 copy_from_user_toio . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.4.3 snd_malloc_pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.4.4 snd_free_pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.4.5 snd_dma_alloc_pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.4.6 snd_dma_alloc_pages_fallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.4.7 snd_dma_free_pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
The ALSA Driver API v
2 PCM API 12
2.1 PCM Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.1.1 snd_pcm_new_stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.1.2 snd_pcm_new . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
2.1.3 snd_pcm_new_internal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2.1.4 snd_pcm_set_ops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.1.5 snd_pcm_set_sync . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.1.6 snd_interval_rene . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
2.1.7 snd_interval_ratnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.1.8 snd_interval_list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
2.1.9 snd_pcm_hw_rule_add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.1.10 snd_pcm_hw_constraint_mask64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
2.1.11 snd_pcm_hw_constraint_integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.1.12 snd_pcm_hw_constraint_minmax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
2.1.13 snd_pcm_hw_constraint_list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.1.14 snd_pcm_hw_constraint_ratnums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
2.1.15 snd_pcm_hw_constraint_ratdens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.1.16 snd_pcm_hw_constraint_msbits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.1.17 snd_pcm_hw_constraint_step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.1.18 snd_pcm_hw_constraint_pow2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.1.19 snd_pcm_hw_rule_noresample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
2.1.20 snd_pcm_hw_param_value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.1.21 snd_pcm_hw_param_rst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
2.1.22 snd_pcm_hw_param_last . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.1.23 snd_pcm_lib_ioctl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
2.1.24 snd_pcm_period_elapsed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.1.25 snd_pcm_add_chmap_ctls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.1.26 snd_pcm_stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.1.27 snd_pcm_suspend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.1.28 snd_pcm_suspend_all . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
2.2 PCM Format Helpers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.2.1 snd_pcm_format_signed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.2.2 snd_pcm_format_unsigned . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
2.2.3 snd_pcm_format_linear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.2.4 snd_pcm_format_little_endian . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.2.5 snd_pcm_format_big_endian . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
2.2.6 snd_pcm_format_width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
2.2.7 snd_pcm_format_physical_width . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
2.2.8 snd_pcm_format_size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
The ALSA Driver API vi
2.2.9 snd_pcm_format_silence_64 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
2.2.10 snd_pcm_format_set_silence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
2.2.11 snd_pcm_limit_hw_rates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
2.2.12 snd_pcm_rate_to_rate_bit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.2.13 snd_pcm_rate_bit_to_rate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
2.2.14 snd_pcm_rate_mask_intersect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
2.3 PCM Memory Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
2.3.1 snd_pcm_lib_preallocate_free_for_all . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
2.3.2 snd_pcm_lib_preallocate_pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
2.3.3 snd_pcm_lib_preallocate_pages_for_all . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
2.3.4 snd_pcm_sgbuf_ops_page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
2.3.5 snd_pcm_lib_malloc_pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
2.3.6 snd_pcm_lib_free_pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
2.3.7 snd_pcm_lib_free_vmalloc_buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
2.3.8 snd_pcm_lib_get_vmalloc_page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3 Control/Mixer API 35
3.1 General Control Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.1.1 snd_ctl_new1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.1.2 snd_ctl_free_one . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.1.3 snd_ctl_add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.1.4 snd_ctl_replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
3.1.5 snd_ctl_remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
3.1.6 snd_ctl_remove_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
3.1.7 snd_ctl_activate_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
3.1.8 snd_ctl_rename_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
3.1.9 snd_ctl_nd_numid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
3.1.10 snd_ctl_nd_id . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
3.1.11 snd_ctl_enum_info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
3.2 AC97 Codec API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
3.2.1 snd_ac97_write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
3.2.2 snd_ac97_read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
3.2.3 snd_ac97_write_cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
3.2.4 snd_ac97_update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
3.2.5 snd_ac97_update_bits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
3.2.6 snd_ac97_get_short_name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
3.2.7 snd_ac97_bus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
3.2.8 snd_ac97_mixer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
3.2.9 snd_ac97_update_power . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
The ALSA Driver API vii
3.2.10 snd_ac97_suspend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
3.2.11 snd_ac97_resume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
3.2.12 snd_ac97_tune_hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
3.2.13 snd_ac97_set_rate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
3.2.14 snd_ac97_pcm_assign . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
3.2.15 snd_ac97_pcm_open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
3.2.16 snd_ac97_pcm_close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
3.2.17 snd_ac97_pcm_double_rate_rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
3.3 Virtual Master Control API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
3.3.1 snd_ctl_make_virtual_master . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
3.3.2 snd_ctl_add_vmaster_hook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
3.3.3 snd_ctl_sync_vmaster . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
3.3.4 snd_ctl_add_slave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
3.3.5 snd_ctl_add_slave_uncached . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
4 MIDI API 51
4.1 Raw MIDI API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
4.1.1 snd_rawmidi_receive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
4.1.2 snd_rawmidi_transmit_empty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
4.1.3 snd_rawmidi_transmit_peek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
4.1.4 snd_rawmidi_transmit_ack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
4.1.5 snd_rawmidi_transmit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
4.1.6 snd_rawmidi_new . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
4.1.7 snd_rawmidi_set_ops . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
4.2 MPU401-UART API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
4.2.1 snd_mpu401_uart_interrupt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
4.2.2 snd_mpu401_uart_interrupt_tx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
4.2.3 snd_mpu401_uart_new . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
5 Proc Info API 57
5.1 Proc Info Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
5.1.1 snd_iprintf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
5.1.2 snd_info_get_line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
5.1.3 snd_info_get_str . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
5.1.4 snd_info_create_module_entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
5.1.5 snd_info_create_card_entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.1.6 snd_card_proc_new . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
5.1.7 snd_info_free_entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
5.1.8 snd_info_register . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
The ALSA Driver API viii
6 Miscellaneous Functions 62
6.1 Hardware-Dependent Devices API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
6.1.1 snd_hwdep_new . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
6.2 Jack Abstraction Layer API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
6.2.1 snd_jack_new . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
6.2.2 snd_jack_set_parent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
6.2.3 snd_jack_set_key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
6.2.4 snd_jack_report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
6.3 ISA DMA Helpers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
6.3.1 snd_dma_program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
6.3.2 snd_dma_disable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
6.3.3 snd_dma_pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
6.4 Other Helper Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
6.4.1 snd_register_device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
6.4.2 snd_printk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
6.4.3 snd_printd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
6.4.4 snd_BUG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
6.4.5 snd_printd_ratelimit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
6.4.6 snd_BUG_ON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
6.4.7 snd_printdd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
The ALSA Driver API 1 / 68
Chapter 1
Management of Cards and Devices
1.1 Card Management
1.1.1 snd_card_new
snd_card_new create and initialize a soundcard structure
Synopsis
int snd_card_new (struct device * parent, int idx, const char * xid, struct module * module, int extra_size, struct snd_card **
card_ret);
Arguments
parent the parent device object
idx card index (address) [0 ... (SNDRV_CARDS-1)]
xid card identication (ASCII string)
module top level module for locking
extra_size allocate this extra size after the main soundcard structure
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.
1.1.2 snd_card_disconnect
snd_card_disconnect disconnect all APIs from the le-operations (user space)
The ALSA Driver API 2 / 68
Synopsis
int snd_card_disconnect (struct snd_card * card);
Arguments
card soundcard structure
Description
Disconnects all APIs from the le-operations (user space).
Return
Zero, otherwise a negative error code.
Note
The current implementation replaces all active le->f_op with special dummy le operations (they do nothing except release).
1.1.3 snd_card_set_id
snd_card_set_id set card identication name
Synopsis
void snd_card_set_id (struct snd_card * card, const char * nid);
Arguments
card soundcard structure
nid new identication string
Description
This function sets the card identication and checks for name collisions.
1.1.4 snd_card_register
snd_card_register register the soundcard
Synopsis
int snd_card_register (struct snd_card * card);
Arguments
card soundcard structure
The ALSA Driver API 3 / 68
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.
Return
Zero otherwise a negative error code if the registration failed.
1.1.5 snd_component_add
snd_component_add add a component string
Synopsis
int snd_component_add (struct snd_card * card, const char * component);
Arguments
card soundcard structure
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.
1.1.6 snd_card_le_add
snd_card_le_add add the le to the le list of the card
Synopsis
int snd_card_le_add (struct snd_card * card, struct le * le);
Arguments
card soundcard structure
file le pointer
Description
This function adds the le to the le 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.
The ALSA Driver API 4 / 68
Return
zero or a negative error code.
1.1.7 snd_card_le_remove
snd_card_le_remove remove the le from the le list
Synopsis
int snd_card_le_remove (struct snd_card * card, struct le * le);
Arguments
card soundcard structure
file le pointer
Description
This function removes the le formerly added to the card via snd_card_file_add function. If all les 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.
1.1.8 snd_power_wait
snd_power_wait wait until the power-state is changed.
Synopsis
int snd_power_wait (struct snd_card * card, unsigned int power_state);
Arguments
card soundcard structure
power_state expected power state
Description
Waits until the power-state is changed.
Return
Zero if successful, or a negative error code.
The ALSA Driver API 5 / 68
Note
the power lock must be active before call.
1.2 Device Components
1.2.1 snd_device_new
snd_device_new create an ALSA device component
Synopsis
int snd_device_new (struct snd_card * card, enum snd_device_type type, void * device_data, struct snd_device_ops * ops);
Arguments
card the card instance
type the device type, SNDRV_DEV_XXX
device_data the data pointer of this device
ops the operator table
Description
Creates a new device component for the given data pointer. The device will be assigned to the card and managed together by the
card.
The data pointer plays a role as the identier, too, so the pointer address must be unique and unchanged.
Return
Zero if successful, or a negative error code on failure.
1.2.2 snd_device_free
snd_device_free release the device from the card
Synopsis
void snd_device_free (struct snd_card * card, void * device_data);
Arguments
card the card instance
device_data the data pointer to release
The ALSA Driver API 6 / 68
Description
Removes the device from the list on the card and invokes the callbacks, dev_disconnect and dev_free, corresponding to the state.
Then release the device.
1.2.3 snd_device_register
snd_device_register register the device
Synopsis
int snd_device_register (struct snd_card * card, void * device_data);
Arguments
card the card instance
device_data the data pointer to register
Description
Registers the device which was already created via snd_device_new. Usually this is called from snd_card_register,
but it can be called later if any new devices are created after invocation of snd_card_register.
Return
Zero if successful, or a negative error code on failure or if the device not found.
1.3 Module requests and Device File Entries
1.3.1 snd_request_card
snd_request_card try to load the card module
Synopsis
void snd_request_card (int card);
Arguments
card the card number
Description
Tries to load the module snd-card-X for the given card number via request_module. Returns immediately if already loaded.
1.3.2 snd_lookup_minor_data
snd_lookup_minor_data get user data of a registered device
The ALSA Driver API 7 / 68
Synopsis
void * snd_lookup_minor_data (unsigned int minor, int type);
Arguments
minor the minor number
type device type (SNDRV_DEVICE_TYPE_XXX)
Description
Checks that a minor device with the specied type is registered, and returns its user data pointer.
This function increments the reference counter of the card instance if an associated instance with the given minor number and
type is found. The caller must call snd_card_unref appropriately later.
Return
The user data pointer if the specied device is found. NULL otherwise.
1.3.3 snd_register_device_for_dev
snd_register_device_for_dev Register the ALSA device le for the card
Synopsis
int snd_register_device_for_dev (int type, struct snd_card * card, int dev, const struct le_operations * f_ops, void * pri-
vate_data, const char * name, struct device * device);
Arguments
type the device type, SNDRV_DEVICE_TYPE_XXX
card the card instance
dev the device index
f_ops the le operations
private_data user pointer for f_ops->open
name the device le name
device the struct device to link this new device to
Description
Registers an ALSA device le for the given card. The operators have to be set in reg parameter.
Return
Zero if successful, or a negative error code on failure.
The ALSA Driver API 8 / 68
1.3.4 snd_unregister_device
snd_unregister_device unregister the device on the given card
Synopsis
int snd_unregister_device (int type, struct snd_card * card, int dev);
Arguments
type the device type, SNDRV_DEVICE_TYPE_XXX
card the card instance
dev the device index
Description
Unregisters the device le already registered via snd_register_device.
Return
Zero if successful, or a negative error code on failure.
1.4 Memory Management Helpers
1.4.1 copy_to_user_fromio
copy_to_user_fromio copy data from mmio-space to user-space
Synopsis
int copy_to_user_fromio (void __user * dst, const volatile void __iomem * src, size_t count);
Arguments
dst the destination pointer on user-space
src the source pointer on mmio
count the data size to copy in bytes
Description
Copies the data from mmio-space to user-space.
Return
Zero if successful, or non-zero on failure.
The ALSA Driver API 9 / 68
1.4.2 copy_from_user_toio
copy_from_user_toio copy data from user-space to mmio-space
Synopsis
int copy_from_user_toio (volatile void __iomem * dst, const void __user * src, size_t count);
Arguments
dst the destination pointer on mmio-space
src the source pointer on user-space
count the data size to copy in bytes
Description
Copies the data from user-space to mmio-space.
Return
Zero if successful, or non-zero on failure.
1.4.3 snd_malloc_pages
snd_malloc_pages allocate pages with the given size
Synopsis
void * snd_malloc_pages (size_t size, gfp_t gfp_ags);
Arguments
size the size to allocate in bytes
gfp_flags the allocation conditions, GFP_XXX
Description
Allocates the physically contiguous pages with the given size.
Return
The pointer of the buffer, or NULL if no enough memory.
1.4.4 snd_free_pages
snd_free_pages release the pages
The ALSA Driver API 10 / 68
Synopsis
void snd_free_pages (void * ptr, size_t size);
Arguments
ptr the buffer pointer to release
size the allocated buffer size
Description
Releases the buffer allocated via snd_malloc_pages.
1.4.5 snd_dma_alloc_pages
snd_dma_alloc_pages allocate the buffer area according to the given type
Synopsis
int snd_dma_alloc_pages (int type, struct device * device, size_t size, struct snd_dma_buffer * dmab);
Arguments
type the DMA buffer type
device the device pointer
size the buffer size to allocate
dmab buffer allocation record to store the allocated data
Description
Calls the memory-allocator function for the corresponding buffer type.
Return
Zero if the buffer with the given size is allocated successfully, otherwise a negative value on error.
1.4.6 snd_dma_alloc_pages_fallback
snd_dma_alloc_pages_fallback allocate the buffer area according to the given type with fallback
Synopsis
int snd_dma_alloc_pages_fallback (int type, struct device * device, size_t size, struct snd_dma_buffer * dmab);
The ALSA Driver API 11 / 68
Arguments
type the DMA buffer type
device the device pointer
size the buffer size to allocate
dmab buffer allocation record to store the allocated data
Description
Calls the memory-allocator function for the corresponding buffer type. When no space is left, this function reduces the size and
tries to allocate again. The size actually allocated is stored in res_size argument.
Return
Zero if the buffer with the given size is allocated successfully, otherwise a negative value on error.
1.4.7 snd_dma_free_pages
snd_dma_free_pages release the allocated buffer
Synopsis
void snd_dma_free_pages (struct snd_dma_buffer * dmab);
Arguments
dmab the buffer allocation record to release
Description
Releases the allocated buffer via snd_dma_alloc_pages.
The ALSA Driver API 12 / 68
Chapter 2
PCM API
2.1 PCM Core
2.1.1 snd_pcm_new_stream
snd_pcm_new_stream create a new PCM stream
Synopsis
int snd_pcm_new_stream (struct snd_pcm * pcm, int stream, int substream_count);
Arguments
pcm the pcm instance
stream the stream direction, SNDRV_PCM_STREAM_XXX
substream_count the number of substreams
Description
Creates a new stream for the pcm. The corresponding stream on the pcm must have been empty before calling this, i.e. zero must
be given to the argument of snd_pcm_new.
Return
Zero if successful, or a negative error code on failure.
2.1.2 snd_pcm_new
snd_pcm_new create a new PCM instance
Synopsis
int snd_pcm_new (struct snd_card * card, const char * id, int device, int playback_count, int capture_count, struct snd_pcm **
rpcm);
The ALSA Driver API 13 / 68
Arguments
card the card instance
id the id string
device the device index (zero based)
playback_count the number of substreams for playback
capture_count the number of substreams for capture
rpcm the pointer to store the new pcm instance
Description
Creates a new PCM instance.
The pcm operators have to be set afterwards to the new instance via snd_pcm_set_ops.
Return
Zero if successful, or a negative error code on failure.
2.1.3 snd_pcm_new_internal
snd_pcm_new_internal create a new internal PCM instance
Synopsis
int snd_pcm_new_internal (struct snd_card * card, const char * id, int device, int playback_count, int capture_count, struct
snd_pcm ** rpcm);
Arguments
card the card instance
id the id string
device the device index (zero based - shared with normal PCMs)
playback_count the number of substreams for playback
capture_count the number of substreams for capture
rpcm the pointer to store the new pcm instance
Description
Creates a new internal PCM instance with no userspace device or procfs entries. This is used by ASoC Back End PCMs in order
to create a PCM that will only be used internally by kernel drivers. i.e. it cannot be opened by userspace. It provides existing
ASoC components drivers with a substream and access to any private data.
The pcm operators have to be set afterwards to the new instance via snd_pcm_set_ops.
The ALSA Driver API 14 / 68
Return
Zero if successful, or a negative error code on failure.
2.1.4 snd_pcm_set_ops
snd_pcm_set_ops set the PCM operators
Synopsis
void snd_pcm_set_ops (struct snd_pcm * pcm, int direction, const struct snd_pcm_ops * ops);
Arguments
pcm the pcm instance
direction stream direction, SNDRV_PCM_STREAM_XXX
ops the operator table
Description
Sets the given PCM operators to the pcm instance.
2.1.5 snd_pcm_set_sync
snd_pcm_set_sync set the PCM sync id
Synopsis
void snd_pcm_set_sync (struct snd_pcm_substream * substream);
Arguments
substream the pcm substream
Description
Sets the PCM sync identier for the card.
2.1.6 snd_interval_rene
snd_interval_rene rene the interval value of congurator
Synopsis
int snd_interval_rene (struct snd_interval * i, const struct snd_interval * v);
The ALSA Driver API 15 / 68
Arguments
i the interval value to rene
v the interval value to refer to
Description
Renes the interval value with the reference value. The interval is changed to the range satisfying both intervals. The interval
status (min, max, integer, etc.) are evaluated.
Return
Positive if the value is changed, zero if its not changed, or a negative error code.
2.1.7 snd_interval_ratnum
snd_interval_ratnum rene the interval value
Synopsis
int snd_interval_ratnum (struct snd_interval * i, unsigned int rats_count, struct snd_ratnum * rats, unsigned int * nump, un-
signed int * denp);
Arguments
i interval to rene
rats_count number of ratnum_t
rats ratnum_t array
nump pointer to store the resultant numerator
denp pointer to store the resultant denominator
Return
Positive if the value is changed, zero if its not changed, or a negative error code.
2.1.8 snd_interval_list
snd_interval_list rene the interval value from the list
Synopsis
int snd_interval_list (struct snd_interval * i, unsigned int count, const unsigned int * list, unsigned int mask);
The ALSA Driver API 16 / 68
Arguments
i the interval value to rene
count the number of elements in the list
list the value list
mask the bit-mask to evaluate
Description
Renes the interval value from the list. When mask is non-zero, only the elements corresponding to bit 1 are evaluated.
Return
Positive if the value is changed, zero if its not changed, or a negative error code.
2.1.9 snd_pcm_hw_rule_add
snd_pcm_hw_rule_add add the hw-constraint rule
Synopsis
int snd_pcm_hw_rule_add (struct snd_pcm_runtime * runtime, unsigned int cond, int var, snd_pcm_hw_rule_func_t func, void
* private, int dep, ...);
Arguments
runtime the pcm runtime instance
cond condition bits
var the variable to evaluate
func the evaluation function
private the private data pointer passed to function
dep the dependent variables
... variable arguments
Return
Zero if successful, or a negative error code on failure.
2.1.10 snd_pcm_hw_constraint_mask64
snd_pcm_hw_constraint_mask64 apply the given bitmap mask constraint
Synopsis
int snd_pcm_hw_constraint_mask64 (struct snd_pcm_runtime * runtime, snd_pcm_hw_param_t var, u_int64_t mask);
The ALSA Driver API 17 / 68
Arguments
runtime PCM runtime instance
var hw_params variable to apply the mask
mask the 64bit bitmap mask
Description
Apply the constraint of the given bitmap mask to a 64-bit mask parameter.
Return
Zero if successful, or a negative error code on failure.
2.1.11 snd_pcm_hw_constraint_integer
snd_pcm_hw_constraint_integer apply an integer constraint to an interval
Synopsis
int snd_pcm_hw_constraint_integer (struct snd_pcm_runtime * runtime, snd_pcm_hw_param_t var);
Arguments
runtime PCM runtime instance
var hw_params variable to apply the integer constraint
Description
Apply the constraint of integer to an interval parameter.
Return
Positive if the value is changed, zero if its not changed, or a negative error code.
2.1.12 snd_pcm_hw_constraint_minmax
snd_pcm_hw_constraint_minmax apply a min/max range constraint to an interval
Synopsis
int snd_pcm_hw_constraint_minmax (struct snd_pcm_runtime * runtime, snd_pcm_hw_param_t var, unsigned int min, un-
signed int max);
The ALSA Driver API 18 / 68
Arguments
runtime PCM runtime instance
var hw_params variable to apply the range
min the minimal value
max the maximal value
Description
Apply the min/max range constraint to an interval parameter.
Return
Positive if the value is changed, zero if its not changed, or a negative error code.
2.1.13 snd_pcm_hw_constraint_list
snd_pcm_hw_constraint_list apply a list of constraints to a parameter
Synopsis
int snd_pcm_hw_constraint_list (struct snd_pcm_runtime * runtime, unsigned int cond, snd_pcm_hw_param_t var, const struct
snd_pcm_hw_constraint_list * l);
Arguments
runtime PCM runtime instance
cond condition bits
var hw_params variable to apply the list constraint
l list
Description
Apply the list of constraints to an interval parameter.
Return
Zero if successful, or a negative error code on failure.
2.1.14 snd_pcm_hw_constraint_ratnums
snd_pcm_hw_constraint_ratnums apply ratnums constraint to a parameter
Synopsis
int snd_pcm_hw_constraint_ratnums (struct snd_pcm_runtime * runtime, unsigned int cond, snd_pcm_hw_param_t var, struct
snd_pcm_hw_constraint_ratnums * r);
The ALSA Driver API 19 / 68
Arguments
runtime PCM runtime instance
cond condition bits
var hw_params variable to apply the ratnums constraint
r struct snd_ratnums constriants
Return
Zero if successful, or a negative error code on failure.
2.1.15 snd_pcm_hw_constraint_ratdens
snd_pcm_hw_constraint_ratdens apply ratdens constraint to a parameter
Synopsis
int snd_pcm_hw_constraint_ratdens (struct snd_pcm_runtime * runtime, unsigned int cond, snd_pcm_hw_param_t var, struct
snd_pcm_hw_constraint_ratdens * r);
Arguments
runtime PCM runtime instance
cond condition bits
var hw_params variable to apply the ratdens constraint
r struct snd_ratdens constriants
Return
Zero if successful, or a negative error code on failure.
2.1.16 snd_pcm_hw_constraint_msbits
snd_pcm_hw_constraint_msbits add a hw constraint msbits rule
Synopsis
int snd_pcm_hw_constraint_msbits (struct snd_pcm_runtime * runtime, unsigned int cond, unsigned int width, unsigned int
msbits);
Arguments
runtime PCM runtime instance
cond condition bits
width sample bits width
msbits msbits width
The ALSA Driver API 20 / 68
Return
Zero if successful, or a negative error code on failure.
2.1.17 snd_pcm_hw_constraint_step
snd_pcm_hw_constraint_step add a hw constraint step rule
Synopsis
int snd_pcm_hw_constraint_step (struct snd_pcm_runtime * runtime, unsigned int cond, snd_pcm_hw_param_t var, unsigned
long step);
Arguments
runtime PCM runtime instance
cond condition bits
var hw_params variable to apply the step constraint
step step size
Return
Zero if successful, or a negative error code on failure.
2.1.18 snd_pcm_hw_constraint_pow2
snd_pcm_hw_constraint_pow2 add a hw constraint power-of-2 rule
Synopsis
int snd_pcm_hw_constraint_pow2 (struct snd_pcm_runtime * runtime, unsigned int cond, snd_pcm_hw_param_t var);
Arguments
runtime PCM runtime instance
cond condition bits
var hw_params variable to apply the power-of-2 constraint
Return
Zero if successful, or a negative error code on failure.
2.1.19 snd_pcm_hw_rule_noresample
snd_pcm_hw_rule_noresample add a rule to allow disabling hw resampling
The ALSA Driver API 21 / 68
Synopsis
int snd_pcm_hw_rule_noresample (struct snd_pcm_runtime * runtime, unsigned int base_rate);
Arguments
runtime PCM runtime instance
base_rate the rate at which the hardware does not resample
Return
Zero if successful, or a negative error code on failure.
2.1.20 snd_pcm_hw_param_value
snd_pcm_hw_param_value return params eld var value
Synopsis
int snd_pcm_hw_param_value (const struct snd_pcm_hw_params * params, snd_pcm_hw_param_t var, int * dir);
Arguments
params the hw_params instance
var parameter to retrieve
dir pointer to the direction (-1,0,1) or NULL
Return
The value for eld var if its xed in conguration space dened by params. -EINVAL otherwise.
2.1.21 snd_pcm_hw_param_rst
snd_pcm_hw_param_rst rene cong space and return minimum value
Synopsis
int snd_pcm_hw_param_rst (struct snd_pcm_substream * pcm, struct snd_pcm_hw_params * params, snd_pcm_hw_param_t
var, int * dir);
Arguments
pcm PCM instance
params the hw_params instance
var parameter to retrieve
dir pointer to the direction (-1,0,1) or NULL
The ALSA Driver API 22 / 68
Description
Inside conguration space dened by params remove from var all values > minimum. Reduce conguration space accordingly.
Return
The minimum, or a negative error code on failure.
2.1.22 snd_pcm_hw_param_last
snd_pcm_hw_param_last rene cong space and return maximum value
Synopsis
int snd_pcm_hw_param_last (struct snd_pcm_substream * pcm, struct snd_pcm_hw_params * params, snd_pcm_hw_param_t
var, int * dir);
Arguments
pcm PCM instance
params the hw_params instance
var parameter to retrieve
dir pointer to the direction (-1,0,1) or NULL
Description
Inside conguration space dened by params remove from var all values < maximum. Reduce conguration space accordingly.
Return
The maximum, or a negative error code on failure.
2.1.23 snd_pcm_lib_ioctl
snd_pcm_lib_ioctl a generic PCM ioctl callback
Synopsis
int snd_pcm_lib_ioctl (struct snd_pcm_substream * substream, unsigned int cmd, void * arg);
Arguments
substream the pcm substream instance
cmd ioctl command
arg ioctl argument
The ALSA Driver API 23 / 68
Description
Processes the generic ioctl commands for PCM. Can be passed as the ioctl callback for PCM ops.
Return
Zero if successful, or a negative error code on failure.
2.1.24 snd_pcm_period_elapsed
snd_pcm_period_elapsed update the pcm status for the next period
Synopsis
void snd_pcm_period_elapsed (struct snd_pcm_substream * substream);
Arguments
substream the pcm substream instance
Description
This function is called from the interrupt handler when the PCM has processed the period size. It will update the current pointer,
wake up sleepers, etc.
Even if more than one periods have elapsed since the last call, you have to call this only once.
2.1.25 snd_pcm_add_chmap_ctls
snd_pcm_add_chmap_ctls create channel-mapping control elements
Synopsis
int snd_pcm_add_chmap_ctls (struct snd_pcm* pcm, int stream, const struct snd_pcm_chmap_elem* chmap, int max_channels,
unsigned long private_value, struct snd_pcm_chmap ** info_ret);
Arguments
pcm the assigned PCM instance
stream stream direction
chmap channel map elements (for query)
max_channels the max number of channels for the stream
private_value the value passed to each kcontrols private_value eld
info_ret store struct snd_pcm_chmap instance if non-NULL
Description
Create channel-mapping control elements assigned to the given PCM stream(s).
The ALSA Driver API 24 / 68
Return
Zero if successful, or a negative error value.
2.1.26 snd_pcm_stop
snd_pcm_stop try to stop all running streams in the substream group
Synopsis
int snd_pcm_stop (struct snd_pcm_substream * substream, snd_pcm_state_t state);
Arguments
substream the PCM substream instance
state PCM state after stopping the stream
Description
The state of each stream is then changed to the given state unconditionally.
Return
Zero if successful, or a negative error code.
2.1.27 snd_pcm_suspend
snd_pcm_suspend trigger SUSPEND to all linked streams
Synopsis
int snd_pcm_suspend (struct snd_pcm_substream * substream);
Arguments
substream the PCM substream
Description
After this call, all streams are changed to SUSPENDED state.
Return
Zero if successful (or substream is NULL), or a negative error code.
2.1.28 snd_pcm_suspend_all
snd_pcm_suspend_all trigger SUSPEND to all substreams in the given pcm
The ALSA Driver API 25 / 68
Synopsis
int snd_pcm_suspend_all (struct snd_pcm * pcm);
Arguments
pcm the PCM instance
Description
After this call, all streams are changed to SUSPENDED state.
Return
Zero if successful (or pcm is NULL), or a negative error code.
2.2 PCM Format Helpers
2.2.1 snd_pcm_format_signed
snd_pcm_format_signed Check the PCM format is signed linear
Synopsis
int snd_pcm_format_signed (snd_pcm_format_t format);
Arguments
format the format to check
Return
1 if the given PCM format is signed linear, 0 if unsigned linear, and a negative error code for non-linear formats.
2.2.2 snd_pcm_format_unsigned
snd_pcm_format_unsigned Check the PCM format is unsigned linear
Synopsis
int snd_pcm_format_unsigned (snd_pcm_format_t format);
Arguments
format the format to check
The ALSA Driver API 26 / 68
Return
1 if the given PCM format is unsigned linear, 0 if signed linear, and a negative error code for non-linear formats.
2.2.3 snd_pcm_format_linear
snd_pcm_format_linear Check the PCM format is linear
Synopsis
int snd_pcm_format_linear (snd_pcm_format_t format);
Arguments
format the format to check
Return
1 if the given PCM format is linear, 0 if not.
2.2.4 snd_pcm_format_little_endian
snd_pcm_format_little_endian Check the PCM format is little-endian
Synopsis
int snd_pcm_format_little_endian (snd_pcm_format_t format);
Arguments
format the format to check
Return
1 if the given PCM format is little-endian, 0 if big-endian, or a negative error code if endian not specied.
2.2.5 snd_pcm_format_big_endian
snd_pcm_format_big_endian Check the PCM format is big-endian
Synopsis
int snd_pcm_format_big_endian (snd_pcm_format_t format);
Arguments
format the format to check
The ALSA Driver API 27 / 68
Return
1 if the given PCM format is big-endian, 0 if little-endian, or a negative error code if endian not specied.
2.2.6 snd_pcm_format_width
snd_pcm_format_width return the bit-width of the format
Synopsis
int snd_pcm_format_width (snd_pcm_format_t format);
Arguments
format the format to check
Return
The bit-width of the format, or a negative error code if unknown format.
2.2.7 snd_pcm_format_physical_width
snd_pcm_format_physical_width return the physical bit-width of the format
Synopsis
int snd_pcm_format_physical_width (snd_pcm_format_t format);
Arguments
format the format to check
Return
The physical bit-width of the format, or a negative error code if unknown format.
2.2.8 snd_pcm_format_size
snd_pcm_format_size return the byte size of samples on the given format
Synopsis
ssize_t snd_pcm_format_size (snd_pcm_format_t format, size_t samples);
Arguments
format the format to check
samples sampling rate
The ALSA Driver API 28 / 68
Return
The byte size of the given samples for the format, or a negative error code if unknown format.
2.2.9 snd_pcm_format_silence_64
snd_pcm_format_silence_64 return the silent data in 8 bytes array
Synopsis
const unsigned char * snd_pcm_format_silence_64 (snd_pcm_format_t format);
Arguments
format the format to check
Return
The format pattern to ll or NULL if error.
2.2.10 snd_pcm_format_set_silence
snd_pcm_format_set_silence set the silence data on the buffer
Synopsis
int snd_pcm_format_set_silence (snd_pcm_format_t format, void * data, unsigned int samples);
Arguments
format the PCM format
data the buffer pointer
samples the number of samples to set silence
Description
Sets the silence data on the buffer for the given samples.
Return
Zero if successful, or a negative error code on failure.
2.2.11 snd_pcm_limit_hw_rates
snd_pcm_limit_hw_rates determine rate_min/rate_max elds
The ALSA Driver API 29 / 68
Synopsis
int snd_pcm_limit_hw_rates (struct snd_pcm_runtime * runtime);
Arguments
runtime the runtime instance
Description
Determines the rate_min and rate_max elds from the rates bits of the given runtime->hw.
Return
Zero if successful.
2.2.12 snd_pcm_rate_to_rate_bit
snd_pcm_rate_to_rate_bit converts sample rate to SNDRV_PCM_RATE_xxx bit
Synopsis
unsigned int snd_pcm_rate_to_rate_bit (unsigned int rate);
Arguments
rate the sample rate to convert
Return
The SNDRV_PCM_RATE_xxx ag that corresponds to the given rate, or SNDRV_PCM_RATE_KNOT for an unknown rate.
2.2.13 snd_pcm_rate_bit_to_rate
snd_pcm_rate_bit_to_rate converts SNDRV_PCM_RATE_xxx bit to sample rate
Synopsis
unsigned int snd_pcm_rate_bit_to_rate (unsigned int rate_bit);
Arguments
rate_bit the rate bit to convert
Return
The sample rate that corresponds to the given SNDRV_PCM_RATE_xxx ag or 0 for an unknown rate bit.
The ALSA Driver API 30 / 68
2.2.14 snd_pcm_rate_mask_intersect
snd_pcm_rate_mask_intersect computes the intersection between two rate masks
Synopsis
unsigned int snd_pcm_rate_mask_intersect (unsigned int rates_a, unsigned int rates_b);
Arguments
rates_a The rst rate mask
rates_b The second rate mask
Description
This function computes the rates that are supported by both rate masks passed to the function. It will take care of the special
handling of SNDRV_PCM_RATE_CONTINUOUS and SNDRV_PCM_RATE_KNOT.
Return
A rate mask containing the rates that are supported by both rates_a and rates_b.
2.3 PCM Memory Management
2.3.1 snd_pcm_lib_preallocate_free_for_all
snd_pcm_lib_preallocate_free_for_all release all pre-allocated buffers on the pcm
Synopsis
int snd_pcm_lib_preallocate_free_for_all (struct snd_pcm * pcm);
Arguments
pcm the pcm instance
Description
Releases all the pre-allocated buffers on the given pcm.
Return
Zero if successful, or a negative error code on failure.
2.3.2 snd_pcm_lib_preallocate_pages
snd_pcm_lib_preallocate_pages pre-allocation for the given DMA type
The ALSA Driver API 31 / 68
Synopsis
int snd_pcm_lib_preallocate_pages (struct snd_pcm_substream * substream, int type, struct device * data, size_t size, size_t
max);
Arguments
substream the pcm substream instance
type DMA type (SNDRV_DMA_TYPE_*)
data DMA type dependent data
size the requested pre-allocation size in bytes
max the max. allowed pre-allocation size
Description
Do pre-allocation for the given DMA buffer type.
Return
Zero if successful, or a negative error code on failure.
2.3.3 snd_pcm_lib_preallocate_pages_for_all
snd_pcm_lib_preallocate_pages_for_all pre-allocation for continuous memory type (all substreams)
Synopsis
int snd_pcm_lib_preallocate_pages_for_all (struct snd_pcm * pcm, int type, void * data, size_t size, size_t max);
Arguments
pcm the pcm instance
type DMA type (SNDRV_DMA_TYPE_*)
data DMA type dependent data
size the requested pre-allocation size in bytes
max the max. allowed pre-allocation size
Description
Do pre-allocation to all substreams of the given pcm for the specied DMA type.
Return
Zero if successful, or a negative error code on failure.
The ALSA Driver API 32 / 68
2.3.4 snd_pcm_sgbuf_ops_page
snd_pcm_sgbuf_ops_page get the page struct at the given offset
Synopsis
struct page * snd_pcm_sgbuf_ops_page (struct snd_pcm_substream * substream, unsigned long offset);
Arguments
substream the pcm substream instance
offset the buffer offset
Description
Used as the page callback of PCM ops.
Return
The page struct at the given buffer offset. NULL on failure.
2.3.5 snd_pcm_lib_malloc_pages
snd_pcm_lib_malloc_pages allocate the DMA buffer
Synopsis
int snd_pcm_lib_malloc_pages (struct snd_pcm_substream * substream, size_t size);
Arguments
substream the substream to allocate the DMA buffer to
size the requested buffer size in bytes
Description
Allocates the DMA buffer on the BUS type given earlier to snd_pcm_lib_preallocate_xxx_pages.
Return
1 if the buffer is changed, 0 if not changed, or a negative code on failure.
2.3.6 snd_pcm_lib_free_pages
snd_pcm_lib_free_pages release the allocated DMA buffer.
The ALSA Driver API 33 / 68
Synopsis
int snd_pcm_lib_free_pages (struct snd_pcm_substream * substream);
Arguments
substream the substream to release the DMA buffer
Description
Releases the DMA buffer allocated via snd_pcm_lib_malloc_pages.
Return
Zero if successful, or a negative error code on failure.
2.3.7 snd_pcm_lib_free_vmalloc_buffer
snd_pcm_lib_free_vmalloc_buffer free vmalloc buffer
Synopsis
int snd_pcm_lib_free_vmalloc_buffer (struct snd_pcm_substream * substream);
Arguments
substream the substream with a buffer allocated by snd_pcm_lib_alloc_vmalloc_buffer
Return
Zero if successful, or a negative error code on failure.
2.3.8 snd_pcm_lib_get_vmalloc_page
snd_pcm_lib_get_vmalloc_page map vmalloc buffer offset to page struct
Synopsis
struct page * snd_pcm_lib_get_vmalloc_page (struct snd_pcm_substream * substream, unsigned long offset);
Arguments
substream the substream with a buffer allocated by snd_pcm_lib_alloc_vmalloc_buffer
offset offset in the buffer
Description
This function is to be used as the page callback in the PCM ops.
The ALSA Driver API 34 / 68
Return
The page struct, or NULL on failure.
The ALSA Driver API 35 / 68
Chapter 3
Control/Mixer API
3.1 General Control Interface
3.1.1 snd_ctl_new1
snd_ctl_new1 create a control instance from the template
Synopsis
struct snd_kcontrol * snd_ctl_new1 (const struct snd_kcontrol_new * ncontrol, void * private_data);
Arguments
ncontrol the initialization record
private_data the private data to set
Description
Allocates a new struct snd_kcontrol instance and initialize from the given template. When the access eld of ncontrol is 0, its
assumed as READWRITE access. When the count eld is 0, its assumes as one.
Return
The pointer of the newly generated instance, or NULL on failure.
3.1.2 snd_ctl_free_one
snd_ctl_free_one release the control instance
Synopsis
void snd_ctl_free_one (struct snd_kcontrol * kcontrol);
The ALSA Driver API 36 / 68
Arguments
kcontrol the control instance
Description
Releases the control instance created via snd_ctl_new or snd_ctl_new1. Dont call this after the control was added to the
card.
3.1.3 snd_ctl_add
snd_ctl_add add the control instance to the card
Synopsis
int snd_ctl_add (struct snd_card * card, struct snd_kcontrol * kcontrol);
Arguments
card the card instance
kcontrol the control instance to add
Description
Adds the control instance created via snd_ctl_new or snd_ctl_new1 to the given card. Assigns also an unique numid used
for fast search.
It frees automatically the control which cannot be added.
Return
Zero if successful, or a negative error code on failure.
3.1.4 snd_ctl_replace
snd_ctl_replace replace the control instance of the card
Synopsis
int snd_ctl_replace (struct snd_card * card, struct snd_kcontrol * kcontrol, bool add_on_replace);
Arguments
card the card instance
kcontrol the control instance to replace
add_on_replace add the control if not already added
The ALSA Driver API 37 / 68
Description
Replaces the given control. If the given control does not exist and the add_on_replace ag is set, the control is added. If the
control exists, it is destroyed rst.
It frees automatically the control which cannot be added or replaced.
Return
Zero if successful, or a negative error code on failure.
3.1.5 snd_ctl_remove
snd_ctl_remove remove the control from the card and release it
Synopsis
int snd_ctl_remove (struct snd_card * card, struct snd_kcontrol * kcontrol);
Arguments
card the card instance
kcontrol the control instance to remove
Description
Removes the control from the card and then releases the instance. You dont need to call snd_ctl_free_one. You must be
in the write lock - down_write(card->controls_rwsem).
Return
0 if successful, or a negative error code on failure.
3.1.6 snd_ctl_remove_id
snd_ctl_remove_id remove the control of the given id and release it
Synopsis
int snd_ctl_remove_id (struct snd_card * card, struct snd_ctl_elem_id * id);
Arguments
card the card instance
id the control id to remove
Description
Finds the control instance with the given id, removes it from the card list and releases it.
The ALSA Driver API 38 / 68
Return
0 if successful, or a negative error code on failure.
3.1.7 snd_ctl_activate_id
snd_ctl_activate_id activate/inactivate the control of the given id
Synopsis
int snd_ctl_activate_id (struct snd_card * card, struct snd_ctl_elem_id * id, int active);
Arguments
card the card instance
id the control id to activate/inactivate
active non-zero to activate
Description
Finds the control instance with the given id, and activate or inactivate the control together with notication, if changed.
Return
0 if unchanged, 1 if changed, or a negative error code on failure.
3.1.8 snd_ctl_rename_id
snd_ctl_rename_id replace the id of a control on the card
Synopsis
int snd_ctl_rename_id (struct snd_card * card, struct snd_ctl_elem_id * src_id, struct snd_ctl_elem_id * dst_id);
Arguments
card the card instance
src_id the old id
dst_id the new id
Description
Finds the control with the old id from the card, and replaces the id with the new one.
Return
Zero if successful, or a negative error code on failure.
The ALSA Driver API 39 / 68
3.1.9 snd_ctl_nd_numid
snd_ctl_nd_numid nd the control instance with the given number-id
Synopsis
struct snd_kcontrol * snd_ctl_nd_numid (struct snd_card * card, unsigned int numid);
Arguments
card the card instance
numid the number-id to search
Description
Finds the control instance with the given number-id from the card.
The caller must down card->controls_rwsem before calling this function (if the race condition can happen).
Return
The pointer of the instance if found, or NULL if not.
3.1.10 snd_ctl_nd_id
snd_ctl_nd_id nd the control instance with the given id
Synopsis
struct snd_kcontrol * snd_ctl_nd_id (struct snd_card * card, struct snd_ctl_elem_id * id);
Arguments
card the card instance
id the id to search
Description
Finds the control instance with the given id from the card.
The caller must down card->controls_rwsem before calling this function (if the race condition can happen).
Return
The pointer of the instance if found, or NULL if not.
3.1.11 snd_ctl_enum_info
snd_ctl_enum_info lls the info structure for an enumerated control
The ALSA Driver API 40 / 68
Synopsis
int snd_ctl_enum_info (struct snd_ctl_elem_info * info, unsigned int channels, unsigned int items, const char *const names[]);
Arguments
info the structure to be lled
channels the number of the controls channels; often one
items the number of control values; also the size of names
names[] an array containing the names of all control values
Description
Sets all required elds in info to their appropriate values. If the controls accessibility is not the default (readable and writable),
the caller has to ll info->access.
Return
Zero.
3.2 AC97 Codec API
3.2.1 snd_ac97_write
snd_ac97_write write a value on the given register
Synopsis
void snd_ac97_write (struct snd_ac97 * ac97, unsigned short reg, unsigned short value);
Arguments
ac97 the ac97 instance
reg the register to change
value the value to set
Description
Writes a value on the given register. This will invoke the write callback directly after the register check. This function doesnt
change the register cache unlike #snd_ca97_write_cache, so use this only when you dont want to reect the change to
the suspend/resume state.
3.2.2 snd_ac97_read
snd_ac97_read read a value from the given register
The ALSA Driver API 41 / 68
Synopsis
unsigned short snd_ac97_read (struct snd_ac97 * ac97, unsigned short reg);
Arguments
ac97 the ac97 instance
reg the register to read
Description
Reads a value from the given register. This will invoke the read callback directly after the register check.
Return
The read value.
3.2.3 snd_ac97_write_cache
snd_ac97_write_cache write a value on the given register and update the cache
Synopsis
void snd_ac97_write_cache (struct snd_ac97 * ac97, unsigned short reg, unsigned short value);
Arguments
ac97 the ac97 instance
reg the register to change
value the value to set
Description
Writes a value on the given register and updates the register cache. The cached values are used for the cached-read and the
suspend/resume.
3.2.4 snd_ac97_update
snd_ac97_update update the value on the given register
Synopsis
int snd_ac97_update (struct snd_ac97 * ac97, unsigned short reg, unsigned short value);
The ALSA Driver API 42 / 68
Arguments
ac97 the ac97 instance
reg the register to change
value the value to set
Description
Compares the value with the register cache and updates the value only when the value is changed.
Return
1 if the value is changed, 0 if no change, or a negative code on failure.
3.2.5 snd_ac97_update_bits
snd_ac97_update_bits update the bits on the given register
Synopsis
int snd_ac97_update_bits (struct snd_ac97 * ac97, unsigned short reg, unsigned short mask, unsigned short value);
Arguments
ac97 the ac97 instance
reg the register to change
mask the bit-mask to change
value the value to set
Description
Updates the masked-bits on the given register only when the value is changed.
Return
1 if the bits are changed, 0 if no change, or a negative code on failure.
3.2.6 snd_ac97_get_short_name
snd_ac97_get_short_name retrieve codec name
Synopsis
const char * snd_ac97_get_short_name (struct snd_ac97 * ac97);
The ALSA Driver API 43 / 68
Arguments
ac97 the codec instance
Return
The short identifying name of the codec.
3.2.7 snd_ac97_bus
snd_ac97_bus create an AC97 bus component
Synopsis
int snd_ac97_bus (struct snd_card * card, int num, struct snd_ac97_bus_ops * ops, void * private_data, struct snd_ac97_bus **
rbus);
Arguments
card the card instance
num the bus number
ops the bus callbacks table
private_data private data pointer for the new instance
rbus the pointer to store the new AC97 bus instance.
Description
Creates an AC97 bus component. An struct snd_ac97_bus instance is newly allocated and initialized.
The ops table must include valid callbacks (at least read and write). The other callbacks, wait and reset, are not mandatory.
The clock is set to 48000. If another clock is needed, set (*rbus)->clock manually.
The AC97 bus instance is registered as a low-level device, so you dont have to release it manually.
Return
Zero if successful, or a negative error code on failure.
3.2.8 snd_ac97_mixer
snd_ac97_mixer create an Codec97 component
Synopsis
int snd_ac97_mixer (struct snd_ac97_bus * bus, struct snd_ac97_template * template, struct snd_ac97 ** rac97);
The ALSA Driver API 44 / 68
Arguments
bus the AC97 bus which codec is attached to
template the template of ac97, including index, callbacks and the private data.
rac97 the pointer to store the new ac97 instance.
Description
Creates an Codec97 component. An struct snd_ac97 instance is newly allocated and initialized from the template. The codec is
then initialized by the standard procedure.
The template must include the codec number (num) and address (addr), and the private data (private_data).
The ac97 instance is registered as a low-level device, so you dont have to release it manually.
Return
Zero if successful, or a negative error code on failure.
3.2.9 snd_ac97_update_power
snd_ac97_update_power update the powerdown register
Synopsis
int snd_ac97_update_power (struct snd_ac97 * ac97, int reg, int powerup);
Arguments
ac97 the codec instance
reg the rate register, e.g. AC97_PCM_FRONT_DAC_RATE
powerup non-zero when power up the part
Description
Update the AC97 powerdown register bits of the given part.
Return
Zero.
3.2.10 snd_ac97_suspend
snd_ac97_suspend General suspend function for AC97 codec
Synopsis
void snd_ac97_suspend (struct snd_ac97 * ac97);
The ALSA Driver API 45 / 68
Arguments
ac97 the ac97 instance
Description
Suspends the codec, power down the chip.
3.2.11 snd_ac97_resume
snd_ac97_resume General resume function for AC97 codec
Synopsis
void snd_ac97_resume (struct snd_ac97 * ac97);
Arguments
ac97 the ac97 instance
Description
Do the standard resume procedure, power up and restoring the old register values.
3.2.12 snd_ac97_tune_hardware
snd_ac97_tune_hardware tune up the hardware
Synopsis
int snd_ac97_tune_hardware (struct snd_ac97 * ac97, struct ac97_quirk * quirk, const char * override);
Arguments
ac97 the ac97 instance
quirk quirk list
override explicit quirk value (overrides the list if non-NULL)
Description
Do some workaround for each pci device, such as renaming of the headphone (true line-out) control as Master. The quirk-list
must be terminated with a zero-lled entry.
Return
Zero if successful, or a negative error code on failure.
The ALSA Driver API 46 / 68
3.2.13 snd_ac97_set_rate
snd_ac97_set_rate change the rate of the given input/output.
Synopsis
int snd_ac97_set_rate (struct snd_ac97 * ac97, int reg, unsigned int rate);
Arguments
ac97 the ac97 instance
reg the register to change
rate the sample rate to set
Description
Changes the rate of the given input/output on the codec. If the codec doesnt support VAR, the rate must be 48000 (except for
SPDIF).
The valid registers are AC97_PMC_MIC_ADC_RATE, AC97_PCM_FRONT_DAC_RATE, AC97_PCM_LR_ADC_RATE. AC97_PCM_SURR_DAC_RATE
and AC97_PCM_LFE_DAC_RATE are accepted if the codec supports them. AC97_SPDIF is accepted as a pseudo register to
modify the SPDIF status bits.
Return
Zero if successful, or a negative error code on failure.
3.2.14 snd_ac97_pcm_assign
snd_ac97_pcm_assign assign AC97 slots to given PCM streams
Synopsis
int snd_ac97_pcm_assign (struct snd_ac97_bus * bus, unsigned short pcms_count, const struct ac97_pcm * pcms);
Arguments
bus the ac97 bus instance
pcms_count count of PCMs to be assigned
pcms PCMs to be assigned
Description
It assigns available AC97 slots for given PCMs. If none or only some slots are available, pcm->xxx.slots and pcm->xxx.rslots[]
members are reduced and might be zero.
The ALSA Driver API 47 / 68
Return
Zero if successful, or a negative error code on failure.
3.2.15 snd_ac97_pcm_open
snd_ac97_pcm_open opens the given AC97 pcm
Synopsis
int snd_ac97_pcm_open (struct ac97_pcm * pcm, unsigned int rate, enum ac97_pcm_cfg cfg, unsigned short slots);
Arguments
pcm the ac97 pcm instance
rate rate in Hz, if codec does not support VRA, this value must be 48000Hz
cfg output stream characteristics
slots a subset of allocated slots (snd_ac97_pcm_assign) for this pcm
Description
It locks the specied slots and sets the given rate to AC97 registers.
Return
Zero if successful, or a negative error code on failure.
3.2.16 snd_ac97_pcm_close
snd_ac97_pcm_close closes the given AC97 pcm
Synopsis
int snd_ac97_pcm_close (struct ac97_pcm * pcm);
Arguments
pcm the ac97 pcm instance
Description
It frees the locked AC97 slots.
Return
Zero.
The ALSA Driver API 48 / 68
3.2.17 snd_ac97_pcm_double_rate_rules
snd_ac97_pcm_double_rate_rules set double rate constraints
Synopsis
int snd_ac97_pcm_double_rate_rules (struct snd_pcm_runtime * runtime);
Arguments
runtime the runtime of the ac97 front playback pcm
Description
Installs the hardware constraint rules to prevent using double rates and more than two channels at the same time.
Return
Zero if successful, or a negative error code on failure.
3.3 Virtual Master Control API
3.3.1 snd_ctl_make_virtual_master
snd_ctl_make_virtual_master Create a virtual master control
Synopsis
struct snd_kcontrol * snd_ctl_make_virtual_master (char * name, const unsigned int * tlv);
Arguments
name name string of the control element to create
tlv optional TLV int array for dB information
Description
Creates a virtual master control with the given name string.
After creating a vmaster element, you can add the slave controls via snd_ctl_add_slave or snd_ctl_add_slave_un
cached.
The optional argument tlv can be used to specify the TLV information for dB scale of the master control. It should be a single el-
ement with #SNDRV_CTL_TLVT_DB_SCALE, #SNDRV_CTL_TLV_DB_MINMAXor #SNDRV_CTL_TLVT_DB_MINMAX_MUTE
type, and should be the max 0dB.
Return
The created control element, or NULL for errors (ENOMEM).
The ALSA Driver API 49 / 68
3.3.2 snd_ctl_add_vmaster_hook
snd_ctl_add_vmaster_hook Add a hook to a vmaster control
Synopsis
int snd_ctl_add_vmaster_hook (struct snd_kcontrol * kcontrol, void (*hook) (void *private_data, int), void * private_data);
Arguments
kcontrol vmaster kctl element
hook the hook function
private_data the private_data pointer to be saved
Description
Adds the given hook to the vmaster control element so that its called at each time when the value is changed.
Return
Zero.
3.3.3 snd_ctl_sync_vmaster
snd_ctl_sync_vmaster Sync the vmaster slaves and hook
Synopsis
void snd_ctl_sync_vmaster (struct snd_kcontrol * kcontrol, bool hook_only);
Arguments
kcontrol vmaster kctl element
hook_only sync only the hook
Description
Forcibly call the put callback of each slave and call the hook function to synchronize with the current value of the given vmaster
element. NOP when NULL is passed to kcontrol.
3.3.4 snd_ctl_add_slave
snd_ctl_add_slave Add a virtual slave control
Synopsis
int snd_ctl_add_slave (struct snd_kcontrol * master, struct snd_kcontrol * slave);
The ALSA Driver API 50 / 68
Arguments
master vmaster element
slave slave element to add
Description
Add a virtual slave control to the given master element created via snd_ctl_create_virtual_master beforehand.
All slaves must be the same type (returning the same information via info callback). The function doesnt check it, so its your
responsibility.
Also, some additional limitations: at most two channels, logarithmic volume control (dB level) thus no linear volume, master can
only attenuate the volume without gain
Return
Zero if successful or a negative error code.
3.3.5 snd_ctl_add_slave_uncached
snd_ctl_add_slave_uncached Add a virtual slave control
Synopsis
int snd_ctl_add_slave_uncached (struct snd_kcontrol * master, struct snd_kcontrol * slave);
Arguments
master vmaster element
slave slave element to add
Description
Add a virtual slave control to the given master. Unlike snd_ctl_add_slave, the element added via this function is supposed
to have volatile values, and get callback is called at each time quried from the master.
When the control peeks the hardware values directly and the value can be changed by other means than the put callback of the
element, this function should be used to keep the value always up-to-date.
Return
Zero if successful or a negative error code.
The ALSA Driver API 51 / 68
Chapter 4
MIDI API
4.1 Raw MIDI API
4.1.1 snd_rawmidi_receive
snd_rawmidi_receive receive the input data from the device
Synopsis
int snd_rawmidi_receive (struct snd_rawmidi_substream * substream, const unsigned char * buffer, int count);
Arguments
substream the rawmidi substream
buffer the buffer pointer
count the data size to read
Description
Reads the data from the internal buffer.
Return
The size of read data, or a negative error code on failure.
4.1.2 snd_rawmidi_transmit_empty
snd_rawmidi_transmit_empty check whether the output buffer is empty
Synopsis
int snd_rawmidi_transmit_empty (struct snd_rawmidi_substream * substream);
The ALSA Driver API 52 / 68
Arguments
substream the rawmidi substream
Return
1 if the internal output buffer is empty, 0 if not.
4.1.3 snd_rawmidi_transmit_peek
snd_rawmidi_transmit_peek copy data from the internal buffer
Synopsis
int snd_rawmidi_transmit_peek (struct snd_rawmidi_substream * substream, unsigned char * buffer, int count);
Arguments
substream the rawmidi substream
buffer the buffer pointer
count data size to transfer
Description
Copies data from the internal output buffer to the given buffer.
Call this in the interrupt handler when the midi output is ready, and call snd_rawmidi_transmit_ack after the transmission
is nished.
Return
The size of copied data, or a negative error code on failure.
4.1.4 snd_rawmidi_transmit_ack
snd_rawmidi_transmit_ack acknowledge the transmission
Synopsis
int snd_rawmidi_transmit_ack (struct snd_rawmidi_substream * substream, int count);
Arguments
substream the rawmidi substream
count the transferred count
The ALSA Driver API 53 / 68
Description
Advances the hardware pointer for the internal output buffer with the given size and updates the condition. Call after the
transmission is nished.
Return
The advanced size if successful, or a negative error code on failure.
4.1.5 snd_rawmidi_transmit
snd_rawmidi_transmit copy from the buffer to the device
Synopsis
int snd_rawmidi_transmit (struct snd_rawmidi_substream * substream, unsigned char * buffer, int count);
Arguments
substream the rawmidi substream
buffer the buffer pointer
count the data size to transfer
Description
Copies data from the buffer to the device and advances the pointer.
Return
The copied size if successful, or a negative error code on failure.
4.1.6 snd_rawmidi_new
snd_rawmidi_new create a rawmidi instance
Synopsis
int snd_rawmidi_new (struct snd_card * card, char * id, int device, int output_count, int input_count, struct snd_rawmidi **
rrawmidi);
Arguments
card the card instance
id the id string
device the device index
output_count the number of output streams
input_count the number of input streams
rrawmidi the pointer to store the new rawmidi instance
The ALSA Driver API 54 / 68
Description
Creates a new rawmidi instance. Use snd_rawmidi_set_ops to set the operators to the new instance.
Return
Zero if successful, or a negative error code on failure.
4.1.7 snd_rawmidi_set_ops
snd_rawmidi_set_ops set the rawmidi operators
Synopsis
void snd_rawmidi_set_ops (struct snd_rawmidi * rmidi, int stream, struct snd_rawmidi_ops * ops);
Arguments
rmidi the rawmidi instance
stream the stream direction, SNDRV_RAWMIDI_STREAM_XXX
ops the operator table
Description
Sets the rawmidi operators for the given stream direction.
4.2 MPU401-UART API
4.2.1 snd_mpu401_uart_interrupt
snd_mpu401_uart_interrupt generic MPU401-UART interrupt handler
Synopsis
irqreturn_t snd_mpu401_uart_interrupt (int irq, void * dev_id);
Arguments
irq the irq number
dev_id mpu401 instance
Description
Processes the interrupt for MPU401-UART i/o.
The ALSA Driver API 55 / 68
Return
IRQ_HANDLED if the interrupt was handled. IRQ_NONE otherwise.
4.2.2 snd_mpu401_uart_interrupt_tx
snd_mpu401_uart_interrupt_tx generic MPU401-UART transmit irq handler
Synopsis
irqreturn_t snd_mpu401_uart_interrupt_tx (int irq, void * dev_id);
Arguments
irq the irq number
dev_id mpu401 instance
Description
Processes the interrupt for MPU401-UART output.
Return
IRQ_HANDLED if the interrupt was handled. IRQ_NONE otherwise.
4.2.3 snd_mpu401_uart_new
snd_mpu401_uart_new create an MPU401-UART instance
Synopsis
int snd_mpu401_uart_new (struct snd_card * card, int device, unsigned short hardware, unsigned long port, unsigned int
info_ags, int irq, struct snd_rawmidi ** rrawmidi);
Arguments
card the card instance
device the device index, zero-based
hardware the hardware type, MPU401_HW_XXXX
port the base address of MPU401 port
info_flags bitags MPU401_INFO_XXX
irq the ISA irq number, -1 if not to be allocated
rrawmidi the pointer to store the new rawmidi instance
The ALSA Driver API 56 / 68
Description
Creates a new MPU-401 instance.
Note that the rawmidi instance is returned on the rrawmidi argument, not the mpu401 instance itself. To access to the mpu401
instance, cast from rawmidi->private_data (with struct snd_mpu401 magic-cast).
Return
Zero if successful, or a negative error code.
The ALSA Driver API 57 / 68
Chapter 5
Proc Info API
5.1 Proc Info Interface
5.1.1 snd_iprintf
snd_iprintf printf on the procfs buffer
Synopsis
int snd_iprintf (struct snd_info_buffer * buffer, const char * fmt, ...);
Arguments
buffer the procfs buffer
fmt the printf format
... variable arguments
Description
Outputs the string on the procfs buffer just like printf.
Return
The size of output string, or a negative error code.
5.1.2 snd_info_get_line
snd_info_get_line read one line from the procfs buffer
Synopsis
int snd_info_get_line (struct snd_info_buffer * buffer, char * line, int len);
The ALSA Driver API 58 / 68
Arguments
buffer the procfs buffer
line the buffer to store
len the max. buffer size - 1
Description
Reads one line from the buffer and stores the string.
Return
Zero if successful, or 1 if error or EOF.
5.1.3 snd_info_get_str
snd_info_get_str parse a string token
Synopsis
const char * snd_info_get_str (char * dest, const char * src, int len);
Arguments
dest the buffer to store the string token
src the original string
len the max. length of token - 1
Description
Parses the original string and copy a token to the given string buffer.
Return
The updated pointer of the original string so that it can be used for the next call.
5.1.4 snd_info_create_module_entry
snd_info_create_module_entry create an info entry for the given module
Synopsis
struct snd_info_entry * snd_info_create_module_entry (struct module * module, const char * name, struct snd_info_entry *
parent);
The ALSA Driver API 59 / 68
Arguments
module the module pointer
name the le name
parent the parent directory
Description
Creates a new info entry and assigns it to the given module.
Return
The pointer of the new instance, or NULL on failure.
5.1.5 snd_info_create_card_entry
snd_info_create_card_entry create an info entry for the given card
Synopsis
struct snd_info_entry * snd_info_create_card_entry (struct snd_card * card, const char * name, struct snd_info_entry * parent);
Arguments
card the card instance
name the le name
parent the parent directory
Description
Creates a new info entry and assigns it to the given card.
Return
The pointer of the new instance, or NULL on failure.
5.1.6 snd_card_proc_new
snd_card_proc_new create an info entry for the given card
Synopsis
int snd_card_proc_new (struct snd_card * card, const char * name, struct snd_info_entry ** entryp);
The ALSA Driver API 60 / 68
Arguments
card the card instance
name the le name
entryp the pointer to store the new info entry
Description
Creates a new info entry and assigns it to the given card. Unlike snd_info_create_card_entry, this function registers
the info entry as an ALSA device component, so that it can be unregistered/released without explicit call. Also, you dont have
to register this entry via snd_info_register, since this will be registered by snd_card_register automatically.
The parent is assumed as card->proc_root.
For releasing this entry, use snd_device_free instead of snd_info_free_entry.
Return
Zero if successful, or a negative error code on failure.
5.1.7 snd_info_free_entry
snd_info_free_entry release the info entry
Synopsis
void snd_info_free_entry (struct snd_info_entry * entry);
Arguments
entry the info entry
Description
Releases the info entry. Dont call this after registered.
5.1.8 snd_info_register
snd_info_register register the info entry
Synopsis
int snd_info_register (struct snd_info_entry * entry);
Arguments
entry the info entry
The ALSA Driver API 61 / 68
Description
Registers the proc info entry.
Return
Zero if successful, or a negative error code on failure.
The ALSA Driver API 62 / 68
Chapter 6
Miscellaneous Functions
6.1 Hardware-Dependent Devices API
6.1.1 snd_hwdep_new
snd_hwdep_new create a new hwdep instance
Synopsis
int snd_hwdep_new (struct snd_card * card, char * id, int device, struct snd_hwdep ** rhwdep);
Arguments
card the card instance
id the id string
device the device index (zero-based)
rhwdep the pointer to store the new hwdep instance
Description
Creates a new hwdep instance with the given index on the card. The callbacks (hwdep->ops) must be set on the returned instance
after this call manually by the caller.
Return
Zero if successful, or a negative error code on failure.
6.2 Jack Abstraction Layer API
6.2.1 snd_jack_new
snd_jack_new Create a new jack
The ALSA Driver API 63 / 68
Synopsis
int snd_jack_new (struct snd_card * card, const char * id, int type, struct snd_jack ** jjack);
Arguments
card the card instance
id an identifying string for this jack
type a bitmask of enum snd_jack_type values that can be detected by this jack
jjack Used to provide the allocated jack object to the caller.
Description
Creates a new jack object.
Return
Zero if successful, or a negative error code on failure. On success jjack will be initialised.
6.2.2 snd_jack_set_parent
snd_jack_set_parent Set the parent device for a jack
Synopsis
void snd_jack_set_parent (struct snd_jack * jack, struct device * parent);
Arguments
jack The jack to congure
parent The device to set as parent for the jack.
Description
Set the parent for the jack devices in the device tree. This function is only valid prior to registration of the jack. If no parent is
congured then the parent device will be the sound card.
6.2.3 snd_jack_set_key
snd_jack_set_key Set a key mapping on a jack
Synopsis
int snd_jack_set_key (struct snd_jack * jack, enum snd_jack_types type, int keytype);
The ALSA Driver API 64 / 68
Arguments
jack The jack to congure
type Jack report type for this key
keytype Input layer key type to be reported
Description
Map a SND_JACK_BTN_ button type to an input layer key, allowing reporting of keys on accessories via the jack abstraction.
If no mapping is provided but keys are enabled in the jack type then BTN_n numeric buttons will be reported.
If jacks are not reporting via the input API this call will have no effect.
Note that this is intended to be use by simple devices with small numbers of keys that can be reported. It is also possible to
access the input device directly - devices with complex input capabilities on accessories should consider doing this rather than
using this abstraction.
This function may only be called prior to registration of the jack.
Return
Zero if successful, or a negative error code on failure.
6.2.4 snd_jack_report
snd_jack_report Report the current status of a jack
Synopsis
void snd_jack_report (struct snd_jack * jack, int status);
Arguments
jack The jack to report status for
status The current status of the jack
6.3 ISA DMA Helpers
6.3.1 snd_dma_program
snd_dma_program program an ISA DMA transfer
Synopsis
void snd_dma_program (unsigned long dma, unsigned long addr, unsigned int size, unsigned short mode);
The ALSA Driver API 65 / 68
Arguments
dma the dma number
addr the physical address of the buffer
size the DMA transfer size
mode the DMA transfer mode, DMA_MODE_XXX
Description
Programs an ISA DMA transfer for the given buffer.
6.3.2 snd_dma_disable
snd_dma_disable stop the ISA DMA transfer
Synopsis
void snd_dma_disable (unsigned long dma);
Arguments
dma the dma number
Description
Stops the ISA DMA transfer.
6.3.3 snd_dma_pointer
snd_dma_pointer return the current pointer to DMA transfer buffer in bytes
Synopsis
unsigned int snd_dma_pointer (unsigned long dma, unsigned int size);
Arguments
dma the dma number
size the dma transfer size
Return
The current pointer in DMA transfer buffer in bytes.
The ALSA Driver API 66 / 68
6.4 Other Helper Macros
6.4.1 snd_register_device
snd_register_device Register the ALSA device le for the card
Synopsis
int snd_register_device (int type, struct snd_card * card, int dev, const struct le_operations * f_ops, void * private_data, const
char * name);
Arguments
type the device type, SNDRV_DEVICE_TYPE_XXX
card the card instance
dev the device index
f_ops the le operations
private_data user pointer for f_ops->open
name the device le name
Description
Registers an ALSA device le for the given card. The operators have to be set in reg parameter.
This function uses the cards device pointer to link to the correct struct device.
Return
Zero if successful, or a negative error code on failure.
6.4.2 snd_printk
snd_printk printk wrapper
Synopsis
snd_printk ( fmt, args...);
Arguments
fmt format string
args... variable arguments
Description
Works like printk but prints the le and the line of the caller when congured with CONFIG_SND_VERBOSE_PRINTK.
The ALSA Driver API 67 / 68
6.4.3 snd_printd
snd_printd debug printk
Synopsis
snd_printd ( fmt, args...);
Arguments
fmt format string
args... variable arguments
Description
Works like snd_printk for debugging purposes. Ignored when CONFIG_SND_DEBUG is not set.
6.4.4 snd_BUG
snd_BUG give a BUG warning message and stack trace
Synopsis
snd_BUG (void);
Arguments
None
Description
Calls WARN if CONFIG_SND_DEBUG is set. Ignored when CONFIG_SND_DEBUG is not set.
6.4.5 snd_printd_ratelimit
snd_printd_ratelimit
Synopsis
snd_printd_ratelimit (void);
Arguments
None
6.4.6 snd_BUG_ON
snd_BUG_ON debugging check macro
The ALSA Driver API 68 / 68
Synopsis
snd_BUG_ON ( cond);
Arguments
cond condition to evaluate
Description
Has the same behavior as WARN_ON when CONFIG_SND_DEBUG is set, otherwise just evaluates the conditional and returns
the value.
6.4.7 snd_printdd
snd_printdd debug printk
Synopsis
snd_printdd ( format, args...);
Arguments
format format string
args... variable arguments
Description
Works like snd_printk for debugging purposes. Ignored when CONFIG_SND_DEBUG_VERBOSE is not set.