1============================= 2Notes on Kernel OSS-Emulation 3============================= 4 5Jan. 22, 2004 Takashi Iwai <tiwai@suse.de> 6 7 8Modules 9======= 10 11ALSA provides a powerful OSS emulation on the kernel. 12The OSS emulation for PCM, mixer and sequencer devices is implemented 13as add-on kernel modules, snd-pcm-oss, snd-mixer-oss and snd-seq-oss. 14When you need to access the OSS PCM, mixer or sequencer devices, the 15corresponding module has to be loaded. 16 17These modules are loaded automatically when the corresponding service 18is called. The alias is defined ``sound-service-x-y``, where x and y are 19the card number and the minor unit number. Usually you don't have to 20define these aliases by yourself. 21 22Only necessary step for auto-loading of OSS modules is to define the 23card alias in ``/etc/modprobe.d/alsa.conf``, such as:: 24 25 alias sound-slot-0 snd-emu10k1 26 27As the second card, define ``sound-slot-1`` as well. 28Note that you can't use the aliased name as the target name (i.e. 29``alias sound-slot-0 snd-card-0`` doesn't work any more like the old 30modutils). 31 32The currently available OSS configuration is shown in 33/proc/asound/oss/sndstat. This shows in the same syntax of 34/dev/sndstat, which is available on the commercial OSS driver. 35On ALSA, you can symlink /dev/sndstat to this proc file. 36 37Please note that the devices listed in this proc file appear only 38after the corresponding OSS-emulation module is loaded. Don't worry 39even if "NOT ENABLED IN CONFIG" is shown in it. 40 41 42Device Mapping 43============== 44 45ALSA supports the following OSS device files: 46:: 47 48 PCM: 49 /dev/dspX 50 /dev/adspX 51 52 Mixer: 53 /dev/mixerX 54 55 MIDI: 56 /dev/midi0X 57 /dev/amidi0X 58 59 Sequencer: 60 /dev/sequencer 61 /dev/sequencer2 (aka /dev/music) 62 63where X is the card number from 0 to 7. 64 65(NOTE: Some distributions have the device files like /dev/midi0 and 66/dev/midi1. They are NOT for OSS but for tclmidi, which is 67a totally different thing.) 68 69Unlike the real OSS, ALSA cannot use the device files more than the 70assigned ones. For example, the first card cannot use /dev/dsp1 or 71/dev/dsp2, but only /dev/dsp0 and /dev/adsp0. 72 73As seen above, PCM and MIDI may have two devices. Usually, the first 74PCM device (``hw:0,0`` in ALSA) is mapped to /dev/dsp and the secondary 75device (``hw:0,1``) to /dev/adsp (if available). For MIDI, /dev/midi and 76/dev/amidi, respectively. 77 78You can change this device mapping via the module options of 79snd-pcm-oss and snd-rawmidi. In the case of PCM, the following 80options are available for snd-pcm-oss: 81 82dsp_map 83 PCM device number assigned to /dev/dspX 84 (default = 0) 85adsp_map 86 PCM device number assigned to /dev/adspX 87 (default = 1) 88 89For example, to map the third PCM device (``hw:0,2``) to /dev/adsp0, 90define like this: 91:: 92 93 options snd-pcm-oss adsp_map=2 94 95The options take arrays. For configuring the second card, specify 96two entries separated by comma. For example, to map the third PCM 97device on the second card to /dev/adsp1, define like below: 98:: 99 100 options snd-pcm-oss adsp_map=0,2 101 102To change the mapping of MIDI devices, the following options are 103available for snd-rawmidi: 104 105midi_map 106 MIDI device number assigned to /dev/midi0X 107 (default = 0) 108amidi_map 109 MIDI device number assigned to /dev/amidi0X 110 (default = 1) 111 112For example, to assign the third MIDI device on the first card to 113/dev/midi00, define as follows: 114:: 115 116 options snd-rawmidi midi_map=2 117 118 119PCM Mode 120======== 121 122As default, ALSA emulates the OSS PCM with so-called plugin layer, 123i.e. tries to convert the sample format, rate or channels 124automatically when the card doesn't support it natively. 125This will lead to some problems for some applications like quake or 126wine, especially if they use the card only in the MMAP mode. 127 128In such a case, you can change the behavior of PCM per application by 129writing a command to the proc file. There is a proc file for each PCM 130stream, ``/proc/asound/cardX/pcmY[cp]/oss``, where X is the card number 131(zero-based), Y the PCM device number (zero-based), and ``p`` is for 132playback and ``c`` for capture, respectively. Note that this proc file 133exists only after snd-pcm-oss module is loaded. 134 135The command sequence has the following syntax: 136:: 137 138 app_name fragments fragment_size [options] 139 140``app_name`` is the name of application with (higher priority) or without 141path. 142``fragments`` specifies the number of fragments or zero if no specific 143number is given. 144``fragment_size`` is the size of fragment in bytes or zero if not given. 145``options`` is the optional parameters. The following options are 146available: 147 148disable 149 the application tries to open a pcm device for 150 this channel but does not want to use it. 151direct 152 don't use plugins 153block 154 force block open mode 155non-block 156 force non-block open mode 157partial-frag 158 write also partial fragments (affects playback only) 159no-silence 160 do not fill silence ahead to avoid clicks 161 162The ``disable`` option is useful when one stream direction (playback or 163capture) is not handled correctly by the application although the 164hardware itself does support both directions. 165The ``direct`` option is used, as mentioned above, to bypass the automatic 166conversion and useful for MMAP-applications. 167For example, to playback the first PCM device without plugins for 168quake, send a command via echo like the following: 169:: 170 171 % echo "quake 0 0 direct" > /proc/asound/card0/pcm0p/oss 172 173While quake wants only playback, you may append the second command 174to notify driver that only this direction is about to be allocated: 175:: 176 177 % echo "quake 0 0 disable" > /proc/asound/card0/pcm0c/oss 178 179The permission of proc files depend on the module options of snd. 180As default it's set as root, so you'll likely need to be superuser for 181sending the command above. 182 183The block and non-block options are used to change the behavior of 184opening the device file. 185 186As default, ALSA behaves as original OSS drivers, i.e. does not block 187the file when it's busy. The -EBUSY error is returned in this case. 188 189This blocking behavior can be changed globally via nonblock_open 190module option of snd-pcm-oss. For using the blocking mode as default 191for OSS devices, define like the following: 192:: 193 194 options snd-pcm-oss nonblock_open=0 195 196The ``partial-frag`` and ``no-silence`` commands have been added recently. 197Both commands are for optimization use only. The former command 198specifies to invoke the write transfer only when the whole fragment is 199filled. The latter stops writing the silence data ahead 200automatically. Both are disabled as default. 201 202You can check the currently defined configuration by reading the proc 203file. The read image can be sent to the proc file again, hence you 204can save the current configuration 205:: 206 207 % cat /proc/asound/card0/pcm0p/oss > /somewhere/oss-cfg 208 209and restore it like 210:: 211 212 % cat /somewhere/oss-cfg > /proc/asound/card0/pcm0p/oss 213 214Also, for clearing all the current configuration, send ``erase`` command 215as below: 216:: 217 218 % echo "erase" > /proc/asound/card0/pcm0p/oss 219 220 221Mixer Elements 222============== 223 224Since ALSA has completely different mixer interface, the emulation of 225OSS mixer is relatively complicated. ALSA builds up a mixer element 226from several different ALSA (mixer) controls based on the name 227string. For example, the volume element SOUND_MIXER_PCM is composed 228from "PCM Playback Volume" and "PCM Playback Switch" controls for the 229playback direction and from "PCM Capture Volume" and "PCM Capture 230Switch" for the capture directory (if exists). When the PCM volume of 231OSS is changed, all the volume and switch controls above are adjusted 232automatically. 233 234As default, ALSA uses the following control for OSS volumes: 235 236==================== ===================== ===== 237OSS volume ALSA control Index 238==================== ===================== ===== 239SOUND_MIXER_VOLUME Master 0 240SOUND_MIXER_BASS Tone Control - Bass 0 241SOUND_MIXER_TREBLE Tone Control - Treble 0 242SOUND_MIXER_SYNTH Synth 0 243SOUND_MIXER_PCM PCM 0 244SOUND_MIXER_SPEAKER PC Speaker 0 245SOUND_MIXER_LINE Line 0 246SOUND_MIXER_MIC Mic 0 247SOUND_MIXER_CD CD 0 248SOUND_MIXER_IMIX Monitor Mix 0 249SOUND_MIXER_ALTPCM PCM 1 250SOUND_MIXER_RECLEV (not assigned) 251SOUND_MIXER_IGAIN Capture 0 252SOUND_MIXER_OGAIN Playback 0 253SOUND_MIXER_LINE1 Aux 0 254SOUND_MIXER_LINE2 Aux 1 255SOUND_MIXER_LINE3 Aux 2 256SOUND_MIXER_DIGITAL1 Digital 0 257SOUND_MIXER_DIGITAL2 Digital 1 258SOUND_MIXER_DIGITAL3 Digital 2 259SOUND_MIXER_PHONEIN Phone 0 260SOUND_MIXER_PHONEOUT Phone 1 261SOUND_MIXER_VIDEO Video 0 262SOUND_MIXER_RADIO Radio 0 263SOUND_MIXER_MONITOR Monitor 0 264==================== ===================== ===== 265 266The second column is the base-string of the corresponding ALSA 267control. In fact, the controls with ``XXX [Playback|Capture] 268[Volume|Switch]`` will be checked in addition. 269 270The current assignment of these mixer elements is listed in the proc 271file, /proc/asound/cardX/oss_mixer, which will be like the following 272:: 273 274 VOLUME "Master" 0 275 BASS "" 0 276 TREBLE "" 0 277 SYNTH "" 0 278 PCM "PCM" 0 279 ... 280 281where the first column is the OSS volume element, the second column 282the base-string of the corresponding ALSA control, and the third the 283control index. When the string is empty, it means that the 284corresponding OSS control is not available. 285 286For changing the assignment, you can write the configuration to this 287proc file. For example, to map "Wave Playback" to the PCM volume, 288send the command like the following: 289:: 290 291 % echo 'VOLUME "Wave Playback" 0' > /proc/asound/card0/oss_mixer 292 293The command is exactly as same as listed in the proc file. You can 294change one or more elements, one volume per line. In the last 295example, both "Wave Playback Volume" and "Wave Playback Switch" will 296be affected when PCM volume is changed. 297 298Like the case of PCM proc file, the permission of proc files depend on 299the module options of snd. you'll likely need to be superuser for 300sending the command above. 301 302As well as in the case of PCM proc file, you can save and restore the 303current mixer configuration by reading and writing the whole file 304image. 305 306 307Duplex Streams 308============== 309 310Note that when attempting to use a single device file for playback and 311capture, the OSS API provides no way to set the format, sample rate or 312number of channels different in each direction. Thus 313:: 314 315 io_handle = open("device", O_RDWR) 316 317will only function correctly if the values are the same in each direction. 318 319To use different values in the two directions, use both 320:: 321 322 input_handle = open("device", O_RDONLY) 323 output_handle = open("device", O_WRONLY) 324 325and set the values for the corresponding handle. 326 327 328Unsupported Features 329==================== 330 331MMAP on ICE1712 driver 332---------------------- 333ICE1712 supports only the unconventional format, interleaved 33410-channels 24bit (packed in 32bit) format. Therefore you cannot mmap 335the buffer as the conventional (mono or 2-channels, 8 or 16bit) format 336on OSS. 337