Alsa support for Maemo SDK (n770): Documentation

This patch file adds a REAME file for alsa-dsp plugin.

Signed-off-by: Eduardo Valentin <eduardo.valentin@indt.org.br>

2 files changed, 184 insertions, 1 deletions

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 <eduardo.valentin@indt.org.br>, 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 <macro>):
+	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.