查看“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==

*'''内核配置'''

如下所示，必须在内核配置中启用ALSA / ASoC和音频图形卡，以启用声音支持。最重要的是，用户必须根据所选的硬件激活CPU和编解码器驱动程序。 用户可以使用Linux [[Menuconfig or how to configure kernel | Menuconfig tool]] 以选择所需的驱动程序：
<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|device tree]]中的声卡配置来配置音频子系统。[[Soundcard configuration|soundcard configuration]] 文章描述了各种板上可用于STM32MPU的声卡。 本文详细介绍了如何配置用于实现声卡的[[:Category:Audio peripherals|audio peripherals]]。

==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>