From afb8fd3c72a9f00018f7335590c173ce4cc2a43d Mon Sep 17 00:00:00 2001 From: Takashi Iwai Date: Wed, 9 Nov 2016 15:52:06 +0100 Subject: ALSA: doc: ReSTize Procfile document A simple conversion from a text file. A new subidrectory, Documentation/sound/designs, was created to put this document. The other API design and implementation docuemnts will be put to that directory in later commits. Signed-off-by: Takashi Iwai --- Documentation/sound/alsa/Procfile.txt | 234 ------------------------------ Documentation/sound/designs/index.rst | 7 + Documentation/sound/designs/procfile.rst | 238 +++++++++++++++++++++++++++++++ Documentation/sound/index.rst | 1 + 4 files changed, 246 insertions(+), 234 deletions(-) delete mode 100644 Documentation/sound/alsa/Procfile.txt create mode 100644 Documentation/sound/designs/index.rst create mode 100644 Documentation/sound/designs/procfile.rst (limited to 'Documentation/sound') diff --git a/Documentation/sound/alsa/Procfile.txt b/Documentation/sound/alsa/Procfile.txt deleted file mode 100644 index 7f8a0d325905..000000000000 --- a/Documentation/sound/alsa/Procfile.txt +++ /dev/null @@ -1,234 +0,0 @@ - Proc Files of ALSA Drivers - ========================== - Takashi Iwai - -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. - - -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 - -: - -pcm - Lists the currently available PCM devices in format of - -: : : - -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. - - -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 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_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 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 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. - - -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. - - -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/ diff --git a/Documentation/sound/designs/index.rst b/Documentation/sound/designs/index.rst new file mode 100644 index 000000000000..82d19fe3c380 --- /dev/null +++ b/Documentation/sound/designs/index.rst @@ -0,0 +1,7 @@ +Designs and Implementations +=========================== + +.. toctree:: + :maxdepth: 2 + + procfile diff --git a/Documentation/sound/designs/procfile.rst b/Documentation/sound/designs/procfile.rst new file mode 100644 index 000000000000..29a466851fd2 --- /dev/null +++ b/Documentation/sound/designs/procfile.rst @@ -0,0 +1,238 @@ +========================== +Proc Files of ALSA Drivers +========================== + +Takashi Iwai + +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. + + +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 + ``-: `` + +pcm + Lists the currently available PCM devices in format of + ``-: : : `` + +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. + + +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 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_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 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 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. + + +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. + + +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/ diff --git a/Documentation/sound/index.rst b/Documentation/sound/index.rst index 64fe47af05b6..e9fbbfff9d0d 100644 --- a/Documentation/sound/index.rst +++ b/Documentation/sound/index.rst @@ -6,6 +6,7 @@ Linux Sound Subsystem Documentation :maxdepth: 2 kernel-api/index + designs/index alsa-configuration hd-audio/index -- cgit v1.2.3