From 8f2bc849bb419221dc08370fd6439632eeae2c1a Mon Sep 17 00:00:00 2001 From: Eduardo Valentin Date: Mon, 6 Nov 2006 14:34:36 +0100 Subject: Alsa support for Maemo SDK (n770): Documentation This patch file adds a REAME file for alsa-dsp plugin. Signed-off-by: Eduardo Valentin --- doc/Makefile.am | 2 +- doc/README-maemo | 183 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 184 insertions(+), 1 deletion(-) create mode 100644 doc/README-maemo diff --git a/doc/Makefile.am b/doc/Makefile.am index efcac16..17e5b99 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,2 +1,2 @@ -EXTRA_DIST = README-pcm-oss README-jack README-pulse \ +EXTRA_DIST = README-pcm-oss README-jack README-pulse README-maemo \ upmix.txt vdownmix.txt samplerate.txt a52.txt diff --git a/doc/README-maemo b/doc/README-maemo new file mode 100644 index 0000000..ea4ea5d --- /dev/null +++ b/doc/README-maemo @@ -0,0 +1,183 @@ +The Debian Package osso-dsp-plugin-alsa +---------------------------- + +Comments regarding the Package + +Eduardo Valentin , Wed, 5 Apr 2006 10:28:06 +0300 + + +OSSO DSP SW <--> ALSA DSP plugin +======================== + +This plugin converts the ALSA API over PCM task nodes protocol. In this way, +ALSA native applications can run over DSP Gateway and use DSP PCM task nodes. + +This plugin provides the PCM type "alsa_dsp". The typical configuration +looks like below: + + # PCM + pcm.!default { + type alsa_dsp + playback_device_file ["/dev/dsptask/pcm2"] + recording_device_file ["/dev/dsptask/pcm_rec"] + } + +Put the above to ~/.asoundrc (or /etc/asound.conf or /usr/share/alsa/alsa.conf), +and use "default" PCM with your ALSA apps. For example: + + % aplay -Ddefault foo.wav + % arecord -Ddefault foo.wav + +The alsa_dsp plugin can have two options for pcm interface: +a. playback_device_file: this is a list of PCM task node device files whose +alsa_dsp plugin is allowed to use to do playback. For example: /dev/dsptask/pcm2. +b. recording_device_file: this is a list of PCM task node device files whose +alsa_dsp plugin is allowed to use to do recording. For example: /dev/dsptask/pcm_rec. + +The alsa_dsp plugin will probe the dsp task node files you provide and +will use the first one whose dsp PCM task is in UNINITIALISED state. +If no dsp PCM task node is usable, alsa_dsp plugin will return an ENODEV +error code. + +For the control interface, this plugin provides the CTL type "dsp_ctl". A +typical configuration is: + # Mixer + ctl.!default { + type dsp_ctl + playback_devices ["/dev/dsptask/pcm2"] + recording_devices ["/dev/dsptask/pcm_rec"] + } + +Put the above to ~/.asoundrc (or /etc/asound.conf or /usr/share/alsa/alsa.conf), +and use "default" CTL with your ALSA apps. For example: + % alsamixer -Ddefault + +The dsp_ctl plugin can have two options for ctl interface: +a. playback_devices: this is a list of PCM task node device files whose +dsp_ctl plugin is allowed to use to do volume control changing. These +devices will be handled under the "PCM Playback Volume" and "PCM Playback Switch" +control names. +b. recording_devices: this is a list of PCM task node device files whose +dsp_ctl plugin is allowed to use to do volume control changing. +These devices will be handled under the "Capture Switch" control name. + +# Supported formats: + +Playback: + 16-bit PCM formats: + S16_LE + S16_BE + U16_LE + U16_BE + 8-bit PCM formats: + A_LAW + MU_LAW + U8 + S8 + Rates: + 8 KHz, 11.025 KHz, 12 KHz, 16 KHz, + 22.050 KHz, 24 KHz, 32 KHz, 44.1 KHz, 48 KHz + Channels: Mono and Stereo +Recording: + 16-bit PCM formats: + S16_LE + 8-bit PCM formats: + A_LAW + MU_LAW + Rates: + 8 KHz + Channels: Mono + +# Compilation +To cross-compile the plugin inside scratchbox environment, you will +need a libasound2 version of binaries and header files installed. +Pthreads is also required. The source directory provides a Makefile. +If you just type: + + % make clean + % make + +under the source tree, it will generate the binaries under the +"bin" sub-directory. Like: + +libasound_module_ctl_dsp_ctl.so and libasound_module_pcm_alsa_dsp.so + +The libasound_module_ctl_dsp_ctl.so is currently a symbolic link to +libasound_module_pcm_alsa_dsp.so. + +You can just copy then to your /usr/lib/alsa-lib/ directory inside your +target file system. + +You can also modify the behaviour of this plugin using macro definitions +while compiling it. Here are macros whose can be used in CFLAGS (-D ): + ERROR_DEBUG It enables error debug output. You have to + change in "debug.h" file. Default is to debug. + DEBUG It enables debug output. You have to change in + "debug.h" file. Default is not to debug. + NORMAL_DSP_TASK It enables utilization of extended fields in + audio_status_info_t data structure (mute, + samples_played_high, samples_played_low). + You can change it in "Makefile". Default + is NORMAL_DSP_TASK enabled. + USE_RESOURCE_MANAGER If set, the resource manager D-BUS interface + will be used for power management instead of + the sysfs file. + ERROR_ON_PM_FAILURE It controls this plugin behaviour if it fails + while openning MIC power management file + (/sys/devices/platform/audio-i2c/mic_enable) + or calling the resource manager request() + method (if USE_RESOURCE_MANAGER is set). + If you enable this macro, this plugin will + return an error code. Otherwise, it will + just print a debug message, and will return + sucess. You can change it in Makefile. Default + is ERROR_ON_PM_FAILURE disabled. + +# Installation +The plugin is installed in /usr/lib/alsa-lib directory as default, +which is the default search path of additional plugins for alsa-lib. + +This plugin is expected to be compatible with any standard ALSA application. +The only requirement is you have to compile it against the same libasound2 you +have installed in your target system. You have to enable the external plugins +support in libasound2: + + % cd $LIB_ASOUND2_SRC + % ./configure --with-pcm-plugins=extplug + +You can get the latest version of libasound2 in http://www.alsa-project.org. +There you can find more instructions of how to compile libasound2. The cross-compilation +for ARM architecture is straightforward inside the scratchbox environment. + + +# Applications + +Alsa-utils: +Also from http://www.alsa-project.org, you can find alsa-utils package sources. +This package constains standard ALSA application, like amixer, alsamixer and +aplay/arecord. + +The compilation of alsa-utils is also straightforward inside scratchbox environment. +The only requirement is you will need to have libasound2 (and libncurses) installed +inside your scratchbox environment to be able to compile alsa-utils. + +After compiling and installing applications on your target, you can +use them with this plugin specifing the correct pcm device. For example, +if you have installed alsaplayer on your target, you can specify an alsa pcm +device with: + target # alsaplayer -d default + +#Limitation + +- While the plugin is using a pcm task node, another applications, +for example gstreamer, can not use the same task node. This will cause +unexpected behaviour. +- If an application does not close alsa device properly, this plugin +will not have chance to release all reserved resouces. One expected +behaviour in this case is to have -EBUSY error for following applications +whose try to open the same alsa device. Partialy solved (version 0.6) +with __attribute__((destructor)) functions. But if the application +receives an uncaught signal, resources may be kept unreleased. +- If many requests to volume information read / write is done in the +same alsa device while it is being used to do playback, this playback +could be affected and some little stops can be heard. -- cgit