This is a quick writeup to get the oss2pulse daemon running as things
stand at 2007-01-11.  Things are as yet unfinished, and this applies
to both fusd and oss2pulse.

Naturally, these steps are intended to be shipped in package form in
the future.

1) Prereq: PulseAudio is already installed and working.
   Hopefully, this is as simple as installing a package for your
   distro.

2) Prereq: The necessary kernel headers/whatever are installed to
   build new kernel modules.  FUSD requires this, as it is a kernel
   module.

2) fetch the fusd and oss2pulse source.  Both live in xiph.org's SVN:
   
   http://svn.xiph.org/trunk/fusd
   http://svn.xiph.org/trunk/oss2pulse

   SVN always holds the most up to date copies.  Tarballs of the
   source versions exactly matching the description/instructions
   in this document are available from:

   http://web.mit.edu/xiphmont/Public/oss2pulse/fusd-monty-20070111.tgz
   http://web.mit.edu/xiphmont/Public/oss2pulse/oss2pulse-20070111.tgz

   IMPORTANT: You need to use the version of fusd from xiph.org
   (fusd-monty); it fixes a few bugs and otherwise differs slightly
   and from the fusd maintained by Kor Nielsen or the much older
   version originally by Jeremy Elson.  Kor and I have been in contact
   and we'll probably reconcile the differences soon.

3) unpack the fusd source and cd into the source's toplevel
   directory.  'make' and then as root, 'make install'.

4) For fusd to work properly, you'll need to add the following new
   udev rule to your udev config (eg, /etc/udev/rules.d/udev.rules
   under Debian, /etc/udev/rules.d/50-udev.rules on Fedora/RHEL):

   # fusd device
   SUBSYSTEM=="fusd",                      NAME="fusd/%k"

5) On systems configured to chown various devices to the console user
   via pam_concole (RedHat-ish systems), /dev/sndstat should be added
   to the <sound>= line in /etc/security/console.perms[whatever],
   something like changing:

   <sound>=/dev/dsp* /dev/audio* /dev/midi* \
           /dev/mixer* /dev/sequencer \
           /dev/sound/* /dev/beep \
           /dev/snd/* 

   to

   <sound>=/dev/dsp* /dev/audio* /dev/midi* \
           /dev/mixer* /dev/sequencer \
           /dev/sound/* /dev/beep \
           /dev/snd/* /dev/sndstat


   (/dev/sndstat doesn't exist in ALSA emulations and so isn't usually
   configured in standard distro udev packages.  However, there are
   still many OSS apps that parse the file for device configuration.)

6) Restart udevd to effect the new config (as root, skill udevd;
   /sbin/udevd -d)

7) modprobe kfusd
   (The make install ran depmod -a already)

   At this point, the fusd devices /dev/fusd/status and
   /dev/fusd/control should exist.  If the modprobe succeeded but no
   fusd devices appeared, doublecheck the udev rule config change and
   make sure udevd restarted successfully.  The kfusd kernel module
   must be inserted after udev has been correctly configured and
   restarted.

8) unpack the oss2pulse source and cd into the oss2pulse source's
   toplevel directory. './configure;make' and then as root 'make
   install'.  The oss2pulse daemon is installed setuid root; this is
   necessary for now, both to talk to the fusd devices (which are root
   accessible) as well as to set up realtime scheduling.

9) rmmod ALSA's OSS emulation modules, at least for the time being.
   They'll conflict with the emulation daemon (and are unneccessary
   once oss2pulse is running):

   /sbin/rmmod snd_pcm_oss snd_mixer_oss

10) Start the pulseaudio daemon (or make sure it is already running).
   It does not matter if it is run with the console user uid or as
   root.

11) Start the oss2pulse daemon ('oss2pulse').  It should disply nothing
   (unless the default debugging output level has been modified in the
   source file oss2pulse.c).  Once you've verified the oss2pulse
   daemon can start / run properly, you may start it with the -d
   oprion, which runs it as a detached daemon.

   Verify that /dev/dsp /dev/mixer and /dev/sndstat exist and are
   accessible by the console user.

Your OSS apps can now talk to PulseAudio.

Troubleshooting:

[I'll fill this in as people send in troubles they've hit in the wild]

1) (Seen on a system I don;t currently have access to, thus the lack
of a verbose error message): SELinux on Fedora boxes appears to
partially refuse shared memory access to PulseAudio.  Symptoms:
playback hangs and PulseAudio reports '/dev/shm: access denied' and
'unable to import memory block'.

I've gotten around this by running pulseaudio as root, anyone know the
real SELinux fix?

2) "libfusd: /dev/fusd/control does not exist; ensure FUSD's kernel module 
   is installed / Unable to register device: Package not installed"

Libfusd returns this error when /dev/fusd/control doesn't exist.  As
the message says, this could be because kfusd hasn't been loaded.  A
second likely reason is that kfusd is loaded (/sbin/lsmod|grep kfusd)
but udevd hasn't been configured to create the /dev/fusd entries.

Doublecheck that the udev configuration includes the rule:

   SUBSYSTEM=="fusd",                      NAME="fusd/%k"

udevd must be restarted for any configuration changes to take effect,
and kfusd must be loaded after udevd has been reconfigured/reloaded.

3) "libfusd: trying to open FUSD control channel: Permission denied
   Unable to register device: Illegal seek"

This error means exactly what it says.  By default, the /dev/fusd
devices are accessible only to root.  oss2pulse is installed setuid
root by default, so this issue shouldn't come up using oss2pulse, but
it will likely affect trying out the various fusd example programs.

3) Libraries not found

By default, all libs instal into /usr/local/lib; make sure that your
ld.so.conf is configured to search /usr/local/lib for libraries.

Monty
20070111