blob: e8dcb9633e7b7bdad8bebbd3a2cdbacaf61fec49 [file] [log] [blame]
Takashi Iwai0c266c42016-11-09 16:18:14 +01001=============================
2Notes on Kernel OSS-Emulation
3=============================
Linus Torvalds1da177e2005-04-16 15:20:36 -07004
Takashi Iwai0c266c42016-11-09 16:18:14 +01005Jan. 22, 2004 Takashi Iwai <tiwai@suse.de>
Linus Torvalds1da177e2005-04-16 15:20:36 -07006
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
Takashi Iwai0c266c42016-11-09 16:18:14 +010018is called. The alias is defined ``sound-service-x-y``, where x and y are
Linus Torvalds1da177e2005-04-16 15:20:36 -070019the 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
Takashi Iwai0c266c42016-11-09 16:18:14 +010023card alias in ``/etc/modprobe.d/alsa.conf``, such as::
Linus Torvalds1da177e2005-04-16 15:20:36 -070024
25 alias sound-slot-0 snd-emu10k1
26
Takashi Iwai0c266c42016-11-09 16:18:14 +010027As the second card, define ``sound-slot-1`` as well.
Linus Torvalds1da177e2005-04-16 15:20:36 -070028Note that you can't use the aliased name as the target name (i.e.
Takashi Iwai0c266c42016-11-09 16:18:14 +010029``alias sound-slot-0 snd-card-0`` doesn't work any more like the old
Linus Torvalds1da177e2005-04-16 15:20:36 -070030modutils).
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:
Takashi Iwai0c266c42016-11-09 16:18:14 +010046::
Linus Torvalds1da177e2005-04-16 15:20:36 -070047
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
Takashi Iwai0c266c42016-11-09 16:18:14 +010066/dev/midi1. They are NOT for OSS but for tclmidi, which is
67a totally different thing.)
Linus Torvalds1da177e2005-04-16 15:20:36 -070068
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
Takashi Iwai0c266c42016-11-09 16:18:14 +010074PCM 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
Linus Torvalds1da177e2005-04-16 15:20:36 -070076/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
Takashi Iwai0c266c42016-11-09 16:18:14 +010082dsp_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)
Linus Torvalds1da177e2005-04-16 15:20:36 -070088
Takashi Iwai0c266c42016-11-09 16:18:14 +010089For example, to map the third PCM device (``hw:0,2``) to /dev/adsp0,
Linus Torvalds1da177e2005-04-16 15:20:36 -070090define like this:
Takashi Iwai0c266c42016-11-09 16:18:14 +010091::
Linus Torvalds1da177e2005-04-16 15:20:36 -070092
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:
Takashi Iwai0c266c42016-11-09 16:18:14 +010098::
Linus Torvalds1da177e2005-04-16 15:20:36 -070099
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
Takashi Iwai0c266c42016-11-09 16:18:14 +0100105midi_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)
Linus Torvalds1da177e2005-04-16 15:20:36 -0700111
112For example, to assign the third MIDI device on the first card to
113/dev/midi00, define as follows:
Takashi Iwai0c266c42016-11-09 16:18:14 +0100114::
Linus Torvalds1da177e2005-04-16 15:20:36 -0700115
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
Takashi Iwai0c266c42016-11-09 16:18:14 +0100130stream, ``/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
Linus Torvalds1da177e2005-04-16 15:20:36 -0700133exists only after snd-pcm-oss module is loaded.
134
135The command sequence has the following syntax:
Takashi Iwai0c266c42016-11-09 16:18:14 +0100136::
Linus Torvalds1da177e2005-04-16 15:20:36 -0700137
138 app_name fragments fragment_size [options]
139
Takashi Iwai0c266c42016-11-09 16:18:14 +0100140``app_name`` is the name of application with (higher priority) or without
Linus Torvalds1da177e2005-04-16 15:20:36 -0700141path.
Takashi Iwai0c266c42016-11-09 16:18:14 +0100142``fragments`` specifies the number of fragments or zero if no specific
Linus Torvalds1da177e2005-04-16 15:20:36 -0700143number is given.
Takashi Iwai0c266c42016-11-09 16:18:14 +0100144``fragment_size`` is the size of fragment in bytes or zero if not given.
145``options`` is the optional parameters. The following options are
Linus Torvalds1da177e2005-04-16 15:20:36 -0700146available:
147
Takashi Iwai0c266c42016-11-09 16:18:14 +0100148disable
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
Linus Torvalds1da177e2005-04-16 15:20:36 -0700161
Takashi Iwai0c266c42016-11-09 16:18:14 +0100162The ``disable`` option is useful when one stream direction (playback or
Linus Torvalds1da177e2005-04-16 15:20:36 -0700163capture) is not handled correctly by the application although the
164hardware itself does support both directions.
Takashi Iwai0c266c42016-11-09 16:18:14 +0100165The ``direct`` option is used, as mentioned above, to bypass the automatic
Linus Torvalds1da177e2005-04-16 15:20:36 -0700166conversion 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:
Takashi Iwai0c266c42016-11-09 16:18:14 +0100169::
Linus Torvalds1da177e2005-04-16 15:20:36 -0700170
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:
Takashi Iwai0c266c42016-11-09 16:18:14 +0100175::
Linus Torvalds1da177e2005-04-16 15:20:36 -0700176
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:
Takashi Iwai0c266c42016-11-09 16:18:14 +0100192::
Linus Torvalds1da177e2005-04-16 15:20:36 -0700193
194 options snd-pcm-oss nonblock_open=0
195
Takashi Iwai0c266c42016-11-09 16:18:14 +0100196The ``partial-frag`` and ``no-silence`` commands have been added recently.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700197Both 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
Takashi Iwai0c266c42016-11-09 16:18:14 +0100205::
Linus Torvalds1da177e2005-04-16 15:20:36 -0700206
207 % cat /proc/asound/card0/pcm0p/oss > /somewhere/oss-cfg
208
209and restore it like
Takashi Iwai0c266c42016-11-09 16:18:14 +0100210::
Linus Torvalds1da177e2005-04-16 15:20:36 -0700211
212 % cat /somewhere/oss-cfg > /proc/asound/card0/pcm0p/oss
213
Takashi Iwai0c266c42016-11-09 16:18:14 +0100214Also, for clearing all the current configuration, send ``erase`` command
Linus Torvalds1da177e2005-04-16 15:20:36 -0700215as below:
Takashi Iwai0c266c42016-11-09 16:18:14 +0100216::
Linus Torvalds1da177e2005-04-16 15:20:36 -0700217
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
Takashi Iwai0c266c42016-11-09 16:18:14 +0100236==================== ===================== =====
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==================== ===================== =====
Linus Torvalds1da177e2005-04-16 15:20:36 -0700265
266The second column is the base-string of the corresponding ALSA
Takashi Iwai0c266c42016-11-09 16:18:14 +0100267control. In fact, the controls with ``XXX [Playback|Capture]
268[Volume|Switch]`` will be checked in addition.
Linus Torvalds1da177e2005-04-16 15:20:36 -0700269
270The current assignment of these mixer elements is listed in the proc
271file, /proc/asound/cardX/oss_mixer, which will be like the following
Takashi Iwai0c266c42016-11-09 16:18:14 +0100272::
Linus Torvalds1da177e2005-04-16 15:20:36 -0700273
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:
Takashi Iwai0c266c42016-11-09 16:18:14 +0100289::
Linus Torvalds1da177e2005-04-16 15:20:36 -0700290
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
Alan Horstmann1919de02007-06-04 23:11:23 +0200307Duplex 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
Takashi Iwai0c266c42016-11-09 16:18:14 +0100313::
314
Alan Horstmann1919de02007-06-04 23:11:23 +0200315 io_handle = open("device", O_RDWR)
Takashi Iwai0c266c42016-11-09 16:18:14 +0100316
Alan Horstmann1919de02007-06-04 23:11:23 +0200317will only function correctly if the values are the same in each direction.
318
319To use different values in the two directions, use both
Takashi Iwai0c266c42016-11-09 16:18:14 +0100320::
321
Alan Horstmann1919de02007-06-04 23:11:23 +0200322 input_handle = open("device", O_RDONLY)
323 output_handle = open("device", O_WRONLY)
Takashi Iwai0c266c42016-11-09 16:18:14 +0100324
Alan Horstmann1919de02007-06-04 23:11:23 +0200325and set the values for the corresponding handle.
326
327
Linus Torvalds1da177e2005-04-16 15:20:36 -0700328Unsupported 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.