kernel/linux/Documentation/sound/alsa/OSS-Emulation.txt

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