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