Documentation/sound/designs/oss-emulation.rst

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