查看“ALSA overview”的源代码

本文提供有关高级Linux声音体系结构（ALSA）的信息，该体系结构为Linux操作系统提供音频功能。

==Purpose==
本文的目的是介绍ALSA框架。

ALSA框架为Linux提供了全面的音频功能，包括音频流的录制和播放，模拟或数字格式，以及路由和混合功能。
ALSA还支持音频中间件，如 [[PulseAudio]], [[GStreamer overview|Gstreamer]]或Android。

== System overview==

[[File:ALSAOverview.png|link=]]

===Component descriptions===

*'''alsa-utils''' (用户空间)
Linux社区提供的ALSA实用程序包包含用于ALSA项目的命令行实用程序(aplay, arecord, amixer, alsamixer ...). 这些工具对于控制声卡很有用。 它们还提供了用于应用程序实现的ALSA API使用示例。
*'''alsa-lib''' (User space)
ALSA库软件包包含需要访问ALSA声音接口的程序 (例如alsa-utils程序) 使用的ALSA库。ALSA库在内核模块提供的音频设备上提供了一个抽象级别，例如PCM和控制抽象。
*'''ALSA framework''' (Kernel space)
ALSA内核提供了一个API，用于实现音频驱动程序和PCM /控制接口，以在用户区公开音频设备。 
PCM接口处理数据流和控制。 该界面管理由ALSA驱动程序导出的控件（音频路径，音量...）。

*'''ASoC framework (ALSA System On Chip)''' (Kernel space)
ALSA片上系统（ASoC）层的作用<ref>[https://www.kernel.org/doc/html/latest/sound/soc/index.html ASoC layer documentation]</ref>是为了改进 ALSA支持嵌入式片上系统处理器和音频编解码器。 ASoC框架提供了一个DMA引擎，该引擎与DMA框架接口以处理音频样本的传输。ASoC还通过DAPM驱动程序支持音频路径的动态电源管理。 ASoC充当ALSA驱动程序，它将嵌入式音频系统分为三种与平台无关的驱动程序：CPU DAI，编解码器和机器驱动程序。

*'''ASoC drivers''' (Kernel space)

ASoC驱动程序允许为ASoC驱动程序类实现与硬件相关的代码：

:* Codec drivers:
::这些驱动程序是后端音频组件的驱动程序。 （请参阅下面的编解码器外围设备）

:* CPU DAI drivers:
::每个STM32音频外设都有一个特定的CPU DAI驱动程序（请参阅下面的CPU DAI外围设备） 每个CPU DAI至少支持以下协议之一：I2S，PCM或S / PDIF。

:* Machine drivers:
::机器驱动程序将CPU DAI和编解码器驱动程序描述并绑定在一起，以创建DAI链接和ALSA声卡。 ASoC框架提供了一种机器驱动程序，用于实现称为“ audio-graph-card”<ref name="Audio graph card bindings">{{CodeSource | Linux kernel | Documentation/devicetree/bindings/sound/audio-graph-card.txt}}</ref><ref name="Device graph bindings">{{CodeSource | Linux kernel | Documentation/devicetree/bindings/graph.txt}}</ref>. 该通用机器驱动程序用于STM32 MPU声卡。

下面的示意图说明了ASoC声卡的总体布局。 请参阅 [[Soundcard configuration|soundcard configuration]] 以查看STM32 MPU板的声卡实现示例。
[[File:asoc_generic_soundcard.png|link=]]

*'''CPU DAI外围设备''' (硬件)
:ST微处理器外围设备提供CPU音频接口。 音频内部外围设备列表可在[[:Category:Audio peripherals|Audio peripherals section]]中找到。

*'''编解码器外围设备''' (硬件)
:编解码器外设是外部（无CPU）硬件音频I / O设备 (即音频编解码器IC，数字麦克风，放大器，简单的IO连接器...).

===API descriptions===
* '''用户空间接口:'''
:ALSA库参考<ref>[http://www.alsa-project.org/alsa-doc/alsa-lib/ ALSA library API]</ref> 记录了userland API库。
* '''内核驱动程序接口:'''
:ALSA内核文档 <ref>[https://www.kernel.org/doc/html/latest/sound/kernel-api/index.html ALSA and ASoC driver API documentation]</ref> 记录了ASOC和ALSA驱动程序API。

==Configuration==

*'''Kernel Configuration'''

The ALSA/ASoC and the audio graph card must be enabled in the kernel configuration, as shown below, to enable the sound support. On top of this, the user has to activate the CPU and Codec drivers according to the chosen hardware. The user can use Linux [[Menuconfig or how to configure kernel | Menuconfig tool]] to select the required drivers: 

<pre>
[*] Device Drivers
    [*] Sound card support
        [*] Advanced Linux Sound Architecture
            [*] ALSA for SoC audio support
                STMicroelectronics STM32 SOC audio support
	             [ ] STM32 SAI interface (Serial Audio Interface) support
	             [ ] STM32 I2S interface (SPI/I2S block) support
	             [ ] STM32 S/PDIF receiver (SPDIFRX) support
                CODEC drivers
	             [ ] ...
                [*] ASoC Audio Graph sound card support
</pre>

*'''Device tree configuration'''

The audio sub-system is configured through the soundcard configuration in the [[Device tree|device tree]]. The [[Soundcard configuration|soundcard configuration]] article describes the soundcards available for STM32MPUs on various board. This article details how to configure the [[:Category:Audio peripherals|audio peripherals]] used to implement the soundcards.

==How to use==

The alsa-utils pakage provides a set of utilities to manage audio devices in the Linux kernel: [https://linux.die.net/man/1/aplay aplay], [https://linux.die.net/man/1/arecord arecord], [https://linux.die.net/man/1/amixer amixer], [https://linux.die.net/man/1/iecset iecset] and [https://linux.die.net/man/1/alsactl alsactl]. An overview of these utilities is given below:

=== Playback ===
*List playback devices
 '''Board $>''' aplay -l

*Play a wav file on card [X] device [Y] 
 '''Board $>''' aplay -D hw:[X],[Y] <filename.wav>

*Play a wav file or a generated signal on card [X] device [Y]
 '''Board $>''' speaker-test -D hw:[X],[Y]

Refer to [[How to play audio]] article, to find examples of playback use cases on STM32MPU boards.

=== Record ===
*List record devices
 '''Board $>''' arecord -l
*Capture audio from card [X] device [Y]
 '''Board $>''' arecord -D hw:[X],[Y] -f dat <filename.wav>

Refer to [[How to record audio]] article, to find examples of record use cases for the STM32MPU boards.

=== Controls ===
*List card [X] controls
 '''Board $>''' amixer -c [X] controls
*Set card [X] controls [Y] to value [Z]
 '''Board $>''' amixer -c [X] cset name='[Y]' '[Z]'
*Store soundcard [X] controls state
 '''Board $>''' alsactl store [X]
*Restore soundcard [X] controls state
 '''Board $>''' alsactl restore [X]

Refer to [[Soundcard configuration]] article to find examples of control configuration for the STM32MPU boards.

=== IEC controls ===
*List iec958 parameters
 '''Board $>''' iecset -h
*Set card [X] iec958 parameter [Y] to value [Z]
 '''Board $>''' iecset -c [X] cset [Y] [Z]
*Dump card [X] iec958 value
 '''Board $>''' iecset -c [X] -x

==How to trace and debug the framework==
This chapter introduces tools useful for debugging and monitoring the audio framework and drivers. It comes as an extension to the [[Linux_tracing,_monitoring_and_debugging]] article.

=== How to monitor ===
This section introduces ALSA framework monitoring methods. Refer to [[:Category:Linux monitoring tools|Linux monitoring tools]] articles for further information.

==== Procfs filesystem ====
The ALSA '''asound''' directory<ref>[https://www.kernel.org/doc/html/latest/sound/designs/procfile.html ALSA proc files]</ref> in [[Pseudo_filesystem|procfs]] file system, provides a lot of information on sound cards. The PCM proc files, provides useful PCM substream debugging information, such as hardware/software parameters, stream status and buffer information.

Examples:
:* List PCM audio devices:
<div style="margin-left: 2em;">
 '''Board $>''' cat /proc/{{highlight|asound}}/pcm
</div>
:* Get hardware parameters of a PCM audio device (device "0" of card "0" here):
<div style="margin-left: 2em;">
 '''Board $>''' cat /proc/{{highlight|asound}}/card0/pcm0p/sub0/hw_params
</div>

==== Debugfs filesystem ====
The '''asoc''' directory in [[Debugfs|debugfs]] file system provides information on sound card components.

Examples:
:* List DAIs
<div style="margin-left: 2em;">
 '''Board $>''' cat /sys/kernel/debug/{{highlight|asoc}}/dais

</div>
:* List DAPMs of "xxx.audio-controller" CPU DAI of "{{highlight|STM32MP1-EV}}" soundcard
<div style="margin-left: 2em;">
 '''Board $>''' ls /sys/kernel/debug/{{highlight|asoc}}/{{highlight|STM32MP1-EV}}/xxx.audio-controller/dapm
</div>

=== How to trace ===
This section introduces tracing methods for ALSA framework. Refer to [[:Category:Linux_tracing_tools|Linux_tracing_tools]] articles to go further.

==== Dynamic traces ====
ALSA framework and driver debug traces can be added to the kernel logs by using the [[How_to_use_the_kernel_dynamic_debug|dynamic debug]] mechanism.
* Example: Activate dynamic trace for SAI Linux driver, and print the traces to the console:

 '''Board $>''' echo -n 'file stm32_sai.c +p; file stm32_sai_sub.c +p' > /sys/kernel/debug/dynamic_debug/control; 
 '''Board $>''' dmesg -n8;

==== Tracing filesystem ====
The Linux kernel offers a [[Pseudo_filesystem|tracefs]] filesystem, provided with Linux kernel tracing framework. ALSA and ASoC have their own tracepoints in this tracing filesystem:
* '''asoc''' entry for ASoC, provides the DAPM, jack and bias level tracepoints.<ref name="tracepoints">{{CodeSource | Linux kernel | Documentation/trace/tracepoint-analysis.rst}}</ref>
* '''snd_pcm''' entry for ALSA, provides the PCM buffers and PCM hardware parameters tracepoints<ref name="tracepoints"></ref><ref name="tracepoints_pcm">[https://www.kernel.org/doc/html/latest/sound/designs/tracepoints.html ALSA tracepoints]</ref>.

===== Activate DAPM traces =====
Prerequisite: the CONFIG_FUNCTION_TRACER configuration must first be enabled in the [[Menuconfig or how to configure kernel | Linux kernel configuration]]
* Enable trace<ref name="tracepoints"></ref>
 '''Board $>''' echo '1' > /sys/kernel/debug/tracing/events/{{highlight|asoc}}/enable
* Check log:
 '''Board $>''' cat /sys/kernel/debug/tracing/trace

===== Activate PCM hardware parameter traces =====
Prerequisite: the CONFIG_FUNCTION_TRACER and CONFIG_SND_DEBUG configurations must first be enabled in the [[Menuconfig or how to configure kernel | Linux kernel configuration]]
* Enable trace<ref name="tracepoints"></ref>
 '''Board $>''' echo '1' > /sys/kernel/debug/tracing/events/{{highlight|snd_pcm}}/enable
* Check log:
 '''Board $>''' cat /sys/kernel/debug/tracing/trace

===== Activate PCM buffer state traces (PCM ring buffer overrun/underrun debugging) =====
Prerequisite: the CONFIG_FUNCTION_TRACER, CONFIG_SND_DEBUG, CONFIG_SND_DEBUG_VERBOSE and SND_PCM_XRUN_DEBUG configurations must first be enabled in the [[Menuconfig or how to configure kernel | Linux kernel configuration]]
* Set XRUN trace verbosity<ref>[http://www.alsa-project.org/main/index.php/XRUN_Debug XRUN Debug]</ref>
 # Enable basic debugging and stack dump
 '''Board $>''' echo 3 > /proc/asound/card0/pcm0p/xrun_debug
* Enable trace<ref name="tracepoints"></ref>
 '''Board $>''' echo '1' > /sys/kernel/debug/tracing/events/{{highlight|snd_pcm}}/enable
* Check log:
 '''Board $>''' cat /sys/kernel/debug/tracing/trace

=== How to debug ===
Refer to the [[:Category:Linux debugging tools|Linux debugging tools]] articles.

==Source code location==

===User space===

* [http://git.alsa-project.org/?p=alsa-lib.git;a=summary alsa-lib sources]
* [http://git.alsa-project.org/?p=alsa-utils.git;a=summary alsa-utils sources]
	
===Kernel space===

* {{CodeSource | Linux kernel | sound/core | ALSA core}}
* {{CodeSource | Linux kernel | sound/soc | ASoC core}}
* {{CodeSource | Linux kernel | sound/soc/stm | ASoC STM32 drivers}}
* {{CodeSource | Linux kernel | sound/soc/codecs | ASoC codecs drivers}}

==References==
<references />

<noinclude>
[[Category:ALSA]]
{{PublicationRequestId | 10644 | 2019-02-06 | StephenG}}
{{ArticleBasedOnModel | Framework overview article model}}
</noinclude>