ALSA 드라이버의 proc 파일

ALSA proc 트리의 기본 구조

이 문서는 Takashi Iwai가 작성한 ALSA 드라이버 proc 파일 안내다. ALSA는 `/proc/asound` 아래에 자체 proc 트리를 두며, 문제를 디버깅할 때 필요한 유용한 정보가 이 트리에 모여 있다.

각 사운드 카드는 `cardX`라는 하위 트리를 가지며 `X`는 0부터 7까지다. 카드에 종속된 파일은 `/proc/asound/card*` 디렉터리에 저장된다.

==========================
Proc Files of ALSA Drivers
==========================

Takashi Iwai <[email protected]>

General
=======

ALSA has its own proc tree, /proc/asound.  Many useful information are
found in this tree.  When you encounter a problem and need debugging,
check the files listed in the following sections.

Each card has its subtree cardX, where X is from 0 to 7. The
card-specific files are stored in the ``card*`` subdirectories.

전역 정보 파일

`cards`는 현재 구성된 ALSA 드라이버 목록과 index, id 문자열, 짧은 설명 및 긴 설명을 표시한다. `version`은 버전 문자열과 컴파일 날짜를, `modules`는 카드별 모듈을, `devices`는 ALSA native 장치 매핑을 나열한다.

`meminfo`는 ALSA 드라이버가 할당한 page 상태를 보여 주며 `CONFIG_SND_DEBUG=y`일 때만 나타난다. `hwdep`는 현재 사용할 수 있는 hwdep 장치를 `<card>-<device>: <name>` 형식으로 나열한다.

`pcm`은 사용 가능한 PCM 장치를 `<card>-<device>: <id>: <name> : <sub-streams>` 형식으로 표시한다. `timer`는 현재 사용 가능한 timer 장치를 나열한다.

`oss/devices`는 OSS 장치 매핑을 보여 준다. `oss/sndstat`은 `/dev/sndstat`과 호환되는 출력을 제공하므로 이 proc 파일을 `/dev/sndstat`에 심볼릭 링크할 수 있다.

Global Information
==================

cards
        Shows the list of currently configured ALSA drivers,
        index, the id string, short and long descriptions.

version
        Shows the version string and compile date.

modules
        Lists the module of each card

devices
        Lists the ALSA native device mappings.

meminfo
        Shows the status of allocated pages via ALSA drivers.
        Appears only when ``CONFIG_SND_DEBUG=y``.

hwdep
        Lists the currently available hwdep devices in format of
        ``<card>-<device>: <name>``

pcm
        Lists the currently available PCM devices in format of
        ``<card>-<device>: <id>: <name> : <sub-streams>``

timer
        Lists the currently available timer devices


oss/devices
        Lists the OSS device mappings.

oss/sndstat
        Provides the output compatible with /dev/sndstat.
        You can symlink this to /dev/sndstat.

카드별 PCM·MIDI·codec 항목

카드별 파일은 `/proc/asound/card*`에 있다. cmipci 같은 일부 드라이버는 자체 proc 항목을 추가하며, 예를 들어 `/proc/asound/card*/cmipci`는 register dump를 제공한다. 이런 파일은 디버깅에 매우 유용하다.

카드에 PCM 장치가 있으면 `pcm0p`, `pcm1c` 같은 디렉터리가 나타난다. `pcm` 다음 숫자는 0부터 시작하는 PCM 장치 번호이고 끝의 `p`와 `c`는 각각 playback과 capture 방향이다. 각 디렉터리는 해당 PCM stream 정보를 가진다.

MIDI I/O 상태는 `midi*` 파일에서 확인한다. 이 파일은 장치 이름과 MIDI 장치를 통해 수신·송신한 byte 수를 표시한다. AC97 codec이 있는 카드에는 `codec97#*` 하위 디렉터리가 생긴다.

OSS mixer 에뮬레이션을 활성화하고 모듈을 적재하면 `oss_mixer` 파일도 나타난다. 이 파일은 OSS mixer 요소와 ALSA control 요소의 현재 매핑을 보여 주며, 파일에 써서 매핑을 바꿀 수 있다. 자세한 내용은 `OSS-Emulation.txt`를 참고한다.

Card Specific Files
===================

The card-specific files are found in ``/proc/asound/card*`` directories.
Some drivers (e.g. cmipci) have their own proc entries for the
register dump, etc (e.g. ``/proc/asound/card*/cmipci`` shows the register
dump).  These files would be really helpful for debugging.

When PCM devices are available on this card, you can see directories
like pcm0p or pcm1c.  They hold the PCM information for each PCM
stream.  The number after ``pcm`` is the PCM device number from 0, and
the last ``p`` or ``c`` means playback or capture direction.  The files in
this subtree is described later.

The status of MIDI I/O is found in ``midi*`` files.  It shows the device
name and the received/transmitted bytes through the MIDI device.

When the card is equipped with AC97 codecs, there are ``codec97#*``
subdirectories (described later).

When the OSS mixer emulation is enabled (and the module is loaded),
oss_mixer file appears here, too.  This shows the current mapping of
OSS mixer elements to the ALSA control elements.  You can change the
mapping by writing to this device.  Read OSS-Emulation.txt for
details.

PCM proc 파일과 XRUN 디버그

`card*/pcm*/info`는 카드 번호, 장치 번호, substream 수 등 PCM 장치의 일반 정보를 보여 준다.

`card*/pcm*/xrun_debug`는 `CONFIG_SND_DEBUG=y`와 `CONFIG_SND_PCM_XRUN_DEBUG=y`일 때 나타난다. ALSA PCM middle layer의 XRUN, 즉 buffer overrun/underrun 상태와 잘못된 PCM position 검사 상태를 표시하며, 정수 값을 써서 동작을 바꿀 수 있다.

# echo 5 > /proc/asound/card0/pcm0p/xrun_debug

값은 bit flag 조합이다. bit 0은 XRUN/jiffies 디버그 메시지를 켜고, bit 1은 XRUN 또는 jiffies 검사 때 stack trace를 추가하며, bit 2는 추가 jiffies 검사를 켠다.

bit 0을 설정하면 XRUN이 검출될 때 kernel log에 메시지가 기록된다. period update 중 잘못된 H/W pointer를 발견했을 때도 메시지가 나오며, period update는 보통 interrupt handler에서 호출된다. bit 1은 stack trace를 함께 표시해 원인 추적을 돕는다.

Linux 2.6.30부터 bit 2로 jiffies 기반 hwptr 검사를 켤 수 있다. 이 검사는 갑작스럽게 잘못된 pointer callback 값을 찾아내지만, pointer를 매끄럽게 갱신하지 않는 대체로 결함 있는 하드웨어에서는 지나치게 많은 보정을 일으킬 수 있다.

`card*/pcm*/sub*/info`는 PCM substream의 일반 정보, `status`는 현재 상태·경과 시간·H/W 위치, `hw_params`는 설정된 hardware parameter, `sw_params`는 software parameter, `prealloc`은 buffer 사전 할당 정보를 보여 준다.

`card*/pcm*/sub*/xrun_injection`은 실행 중인 stream에 fault injection용 XRUN을 발생시킨다. 어떤 값이든 이 proc 파일에 쓰면 동작하며 write-only 항목이다.

PCM Proc Files
==============

``card*/pcm*/info``
        The general information of this PCM device: card #, device #,
        substreams, etc.

``card*/pcm*/xrun_debug``
        This file appears when ``CONFIG_SND_DEBUG=y`` and
        ``CONFIG_SND_PCM_XRUN_DEBUG=y``.
        This shows the status of xrun (= buffer overrun/xrun) and
        invalid PCM position debug/check of ALSA PCM middle layer.
        It takes an integer value, can be changed by writing to this
        file, such as::

                 # echo 5 > /proc/asound/card0/pcm0p/xrun_debug

        The value consists of the following bit flags:

        * bit 0 = Enable XRUN/jiffies debug messages
        * bit 1 = Show stack trace at XRUN / jiffies check
        * bit 2 = Enable additional jiffies check

        When the bit 0 is set, the driver will show the messages to
        kernel log when an xrun is detected.  The debug message is
        shown also when the invalid H/W pointer is detected at the
        update of periods (usually called from the interrupt
        handler).

        When the bit 1 is set, the driver will show the stack trace
        additionally.  This may help the debugging.

        Since 2.6.30, this option can enable the hwptr check using
        jiffies.  This detects spontaneous invalid pointer callback
        values, but can be lead to too much corrections for a (mostly
        buggy) hardware that doesn't give smooth pointer updates.
        This feature is enabled via the bit 2.

``card*/pcm*/sub*/info``
        The general information of this PCM sub-stream.

``card*/pcm*/sub*/status``
        The current status of this PCM sub-stream, elapsed time,
        H/W position, etc.

``card*/pcm*/sub*/hw_params``
        The hardware parameters set for this sub-stream.

``card*/pcm*/sub*/sw_params``
        The soft parameters set for this sub-stream.

``card*/pcm*/sub*/prealloc``
        The buffer pre-allocation information.

``card*/pcm*/sub*/xrun_injection``
        Triggers an XRUN to the running stream when any value is
        written to this proc file.  Used for fault injection.
        This entry is write-only.

AC97 codec 정보와 register 쓰기

`card*/codec97#*/ac97#?-?`는 AC97 codec chip의 이름, capability, 설정 등 일반 정보를 보여 준다. `card*/codec97#0/ac97#?-?+regs`는 디버깅에 유용한 AC97 register dump를 제공한다.

`CONFIG_SND_DEBUG`를 활성화하면 register dump 파일에 두 개의 16진수를 써서 AC97 register를 직접 바꿀 수 있다. 다음 예는 register `02`에 값 `9f1f`를 기록한다.

# echo 02 9f1f > /proc/asound/card0/codec97#0/ac97#0-0+regs

AC97 Codec Information
======================

``card*/codec97#*/ac97#?-?``
        Shows the general information of this AC97 codec chip, such as
        name, capabilities, set up.

``card*/codec97#0/ac97#?-?+regs``
        Shows the AC97 register dump.  Useful for debugging.

        When CONFIG_SND_DEBUG is enabled, you can write to this file for
        changing an AC97 register directly.  Pass two hex numbers.
        For example,

::

        # echo 02 9f1f > /proc/asound/card0/codec97#0/ac97#0-0+regs

USB audio stream과 HD-audio codec

USB audio의 `card*/stream*` 파일은 해당 카드의 각 audio stream 배정과 현재 상태를 보여 주며 디버깅에 매우 유용하다.

HD-audio의 `card*/codec#*`는 일반 codec 정보와 각 widget node의 attribute를 표시한다. `card*/eld#*`는 HDMI 또는 DisplayPort interface에서 사용할 수 있다.

`eld#*`는 연결된 HDMI sink에서 가져온 ELD(EDID Like Data)를 보여 주며 sink의 audio capability와 구성을 설명한다. 일부 ELD field는 `echo name hex_value > eld#*` 형식으로 바꿀 수 있지만, HDMI sink가 제공한 값이 틀렸다고 확신할 때만 사용해야 한다.

ELD 값을 수정해 HDMI audio가 동작하게 되었다면 향후 kernel release에서 고칠 수 있도록 결과를 보고해야 한다.

USB Audio Streams
=================

``card*/stream*``
        Shows the assignment and the current status of each audio stream
        of the given card.  This information is very useful for debugging.


HD-Audio Codecs
===============

``card*/codec#*``
        Shows the general codec information and the attribute of each
        widget node.

``card*/eld#*``
        Available for HDMI or DisplayPort interfaces.
        Shows ELD(EDID Like Data) info retrieved from the attached HDMI sink,
        and describes its audio capabilities and configurations.

        Some ELD fields may be modified by doing ``echo name hex_value > eld#*``.
        Only do this if you are sure the HDMI sink provided value is wrong.
        And if that makes your HDMI audio work, please report to us so that we
        can fix it in future kernel releases.

ALSA sequencer 정보

`seq/drivers`는 현재 사용할 수 있는 ALSA sequencer driver를 나열한다. `seq/clients`는 현재 client와 port 목록뿐 아니라 connection 상태와 running 상태도 보여 준다.

`seq/queues`는 현재 할당되었거나 실행 중인 sequencer queue를, `seq/timer`는 현재 할당되었거나 실행 중인 sequencer timer를 나열한다. `seq/oss`는 OSS 호환 sequencer 항목을 표시한다.

Sequencer Information
=====================

seq/drivers
        Lists the currently available ALSA sequencer drivers.

seq/clients
        Shows the list of currently available sequencer clients and
        ports.  The connection status and the running status are shown
        in this file, too.

seq/queues
        Lists the currently allocated/running sequencer queues.

seq/timer
        Lists the currently allocated/running sequencer timers.

seq/oss
        Lists the OSS-compatible sequencer stuffs.

문제 진단과 버그 보고 자료

PCM 관련 문제라면 먼저 `xrun_debug` 모드를 켠다. 그러면 XRUN이 언제 어디에서 발생했는지 kernel message로 확인할 수 있다.

실제 버그를 보고할 때는 `/proc/asound/cards`에 표시되는 driver/card 이름과, 사용할 수 있다면 `card*/cmipci` 같은 register dump를 포함한다.

PCM 문제에는 PCM substream 디렉터리의 `hw_params`, `sw_params`, `status`에 나타난 설정을 첨부한다. 원문에는 `hw_parms`라고 적힌 부분도 있지만 실제 앞 절의 proc 항목 이름은 `hw_params`다.

Mixer 문제에는 `codec97#*/*` AC97 proc 파일을 포함한다. USB audio/MIDI 문제에는 `lsusb -v` 출력과 카드 디렉터리의 `stream*` 파일을 포함한다.

문서에 기재된 ALSA bug-tracking system 주소는 `https://bugtrack.alsa-project.org/alsa-bug/`이다.

Help For Debugging?
===================

When the problem is related with PCM, first try to turn on xrun_debug
mode.  This will give you the kernel messages when and where xrun
happened.

If it's really a bug, report it with the following information:

- the name of the driver/card, show in ``/proc/asound/cards``
- the register dump, if available (e.g. ``card*/cmipci``)

when it's a PCM problem,

- set-up of PCM, shown in hw_parms, sw_params, and status in the PCM
  sub-stream directory

when it's a mixer problem,

- AC97 proc files, ``codec97#*/*`` files

for USB audio/midi,

- output of ``lsusb -v``
- ``stream*`` files in card directory


The ALSA bug-tracking system is found at:
https://bugtrack.alsa-project.org/alsa-bug/