README

   1
   2  OSS Proxy - emulate OSS device using CUSE
   3
   4  Copyright (C) 2008-2009  SUSE Linux Products GmbH
   5  Copyright (C) 2008-2009  Tejun Heo <tj@kernel.org>
   6
   7 1. What is it?
   8 --------------
   9
  10 Well, first, OSS refers to Open Sound System.  If it still doesn't
  11 ring a bell, think /dev/dsp, /dev/adsp and /dev/mixer.
  12
  13 Currently, Linux supports two audio programming interface - ALSA and
  14 OSS.  The latter one is deprecated and has been that way for a long
  15 time but there still are applications which still use them including
  16 UML (usermode Linux) host sound support.
  17
  18 ALSA contains OSS emulation but sadly the emulation is behind
  19 multiplexing layer (which is in userland) which means that if your
  20 sound card doesn't support multiple audio streams, only either one of
  21 ALSA or OSS interface would be usable at any given moment.
  22
  23 There have been also attempts to emulate OSS in userland using dynamic
  24 library preloading - aoss and more recently padsp.  This works for
  25 many applications but it's just not easy to emulate everything using
  26 the technique.  Things like polling, signals, forking, privilege
  27 changes make it very difficult to emulate things reliably.
  28
  29 OSS Proxy uses CUSE (extension of FUSE allowing character devices to
  30 be implemented in userspace) to implement OSS interface - /dev/dsp,
  31 /dev/adsp and /dev/mixer.  From the POV of the applications, these
  32 devices are proper character devices and behave exactly the same way
  33 so it can be made quite versatile.
  34
  35
  36 2. Hmmm... So, how does the whole thing work?
  37 ---------------------------------------------
  38
  39 The OSS Proxy daemon - osspd - should be started first.  Note that
  40 osspd will fail to start if sound device number regions are already
  41 occupied.  You'll need to turn off OSS or its emulation[1].
  42
  43 On startup, osspd creates /dev/dsp, /dev/adsp and /dev/mixer using
  44 CUSE.  When an application access one of the devices, all IOs are
  45 redirected to osspd via CUSE.  Upon receiving a new DSP open request,
  46 osspd creates a slave process which drops the root privilege and
  47 assumes the opening process's credentials.  After handshaking, osspd
  48 forwards all relevant IOs to the slave which is responsible for
  49 actually playing the sound.
  50
  51 Currently there's only one slave implemented - ossp-padsp, which as
  52 the name suggests forwards (again) the sound to pulseaudio.  To sum
  53 up, the whole pipe looks like the following.
  54
  55  App <-> /dev/dsp <-> CUSE <-> osspd <-> ossp-padsp <-> pulseaudio
  56
  57 Which is a lot of forwarding, but on modern machines, it won't be too
  58 noticeable.
  59
  60
  61 3. What works?
  62 --------------
  63
  64 Well, MIDI part isn't implemented and I doubt it will be in any near
  65 future but except that everything should work.  Playing, recording,
  66 5.1ch, A-V syncing, all should work.  If not, it's a bug, so please
  67 report.
  68
  69 The mixer behaves a bit differently tho.  In the original OSS,
  70 /dev/mixer is the hardware mixer, so adjusting volumes there affects
  71 all audio streams.  When using ossp, each process group gets its own
  72 mixer and the mixer always contains only two knobs - PCM and IGAIN.
  73 Combined with per-stream volume control of pulseaudio, this scheme
  74 works quite well for applications with embedded volume control
  75 although it makes standalone OSS mixer programs virtually useless[2].
  76
  77
  78 4. How do I use it?
  79 -------------------
  80
  81 First you need CUSE support in kernel which might land on 2.6.28 with
  82 sufficient luck[3] and then you also need libfuse which supports
  83 CUSE[4].  Once you have both, it should be easy.  First build it by
  84 running `make'.  You can set OSSPD_CFLAGS, OSSPD_LDFLAGS,
  85 OSSP_PADSP_CFLAGS and OSSP_PADSP_LDFLAGS if you have stuff at
  86 non-default locations.
  87
  88 After build completes, there will be two executables - `osspd' and
  89 `ossp-padsp'.  Just copy them to where other system executables live.
  90 Specific location doesn't matter as long as both files end up in the
  91 same directory.
  92
  93 Execute `osspd'.  It will create the device files and you're all set.
  94 `osspd' uses syslog with LOG_DAEMON facility, so if something doesn't
  95 work take a look at what osspd complains about.
  96
  97
  98 [1] As of this writing, turning on any sound support makes the
  99     soundcore module claim OSS device regions.  Patch to make it claim
 100     OSS device regions only when OSS support or emulation is enabled
 101     is scheduled for 2.6.28.  Even with the patch, soundcore will
 102     claim OSS device regions if OSS support or ALSA OSS emulation is
 103     enabled.  Make sure they're turned off.
 104
 105 [2] If you have a strong reason to use standalone OSS mixer program,
 106     you can play some shell tricks to put it into the same process
 107     group as the target audio application.  e.g. To use aumix with
 108     mpg123 - `(mpg123 asdf.mp3 > /dev/null 2>&1 & aumix)', but
 109     seriously, just use PA or ALSA one.
 110
 111 [3] For the time being, here's the git tree with all the necessary
 112     changes.  This tree is base on top of 2.6.27-rc3.
 113
 114     http://git.kernel.org/?p=linux/kernel/git/tj/misc.git;a=shortlog;h=cuse
 115     git://git.kernel.org/pub/scm/linux/kernel/git/tj/misc.git cuse
 116
 117 [4] And libfuse with the modifications can be found at...
 118
 119     http://userweb.kernel.org/~tj/ossp/fuse-cuse.tar.gz