               Sound Blaster Pro(tm) BSD Unix device driver
                          INSTALLATION NOTES
                                 v1.4

                 Steve Haehnichen <shaehnic@ucsd.edu>

       $Id: INSTALL,v 1.3 1992/06/13 01:45:26 steve Exp steve $
              [ This file is a part of SBlast-BSD-1.4 ]

  These notes are intended to help you install the driver into your 
  386 BSD v4.3 kernel.  This document is still in Beta itself, so it's
  not as complete as I would like it to be.  If you find any parts
  especially confusing, please let me know so I can improve it in future
  releases.

REQUIREMENTS:
------------
The only system this driver has been tested on is Mt. Xinu's Mach386
BSD v4.3.  I would expect any other BSD 386 system to be similar, but
there are always differences.  This is the information I am looking
for.  I am especially interested in the Free bootable BSD386 system
released recently.  (Available via anonymous FTP to agate.berkeley.edu
and many other archive sites.)

This package makes the blatant assumption that you are using the Gnu C
Compiler, version 1.40 or later.  I have made no attempts to allow for
compiler inadequacies, and leave a lot of speed optimizing to GCC.  In
my experience, it is more productive to write explanatory code that
works efficiently, and then let GCC optimize it far more than I could
without obscuring it.  I highly recommend GCC v2.0 and the -O2 option.
The performance increase is very noticeable.

Of course, a Sound Blaster is required.  Currently, this driver is
pretty specific to the Sound Blaster Pro.  Minor modifications should
allow it to work properly on the original Sound Blaster.  If you do
not wish to make these changes, but want to run it on a Sound Blaster,
you could try just using the features supported by the SB, and I would
like to hear how it works out.  In future releases, there should be a
flag to select Pro or not, and maybe just Adlib.  Pro Audio Spectrum
16 and Gravis Ultrasound adaptations are also something I would like
to work on.


ADDRESS SETTINGS:
----------------
Before you install the driver, be very sure you know what your SB Pro
jumper settings are.  The card defaults to DMA channel #1, I/O address
0x220, and IRQ 7.  You need to edit the SB driver to look for your
card in the right place.

The DMA channel is probably best left at #1.  Consult the SB Pro
installation guide if you think you might have a DMA conflict with
other hardware in your machine.  Possible culprits are scanners and
network interfaces.  If you change it from DMA channel #1, edit the
first #define in sb_regs.h to reflect this.

The I/O port can be left at the default 0x220, but can be moved to
0x240 if it conflicts with something else.  Changes to the IO Port
must be reflected in your autoconf.c file.  (See below)

Setting the IRQ (aka: Interrupt ReQuest, or PIC line) will require
some thought.  The default setting is IRQ 7.  This is the same setting
as standard parallel printer I/O cards. which generally works fine
under DOS.  Under Unix, each device should have its own interrupt, so
the default setting of 7 will not work.  In fact, the kernel will not
boot if two devices share the same interrupt.  So, either change the
interrupt on your printer card (not likely), or pick a different
interrupt for the Sound Blaster (easier).

The IRQ jumper on the card has settings for IRQ 2, 5, 7, and 10.  Each
of these has gotcha's, so you may have to experiment.

Interrupt #5 is generally unused in ISA bus machines, but Mach386 is
configured to use it for the third RS-232 Serial port (com3 under
DOS).  If you want to use this interrupt, you must edit autoconf.c and
change the third com entry to have a different interrupt that is
unused.  The line you want to change looks like this:

        {&comdriver, 2, -1, 0, 0,(caddr_t)0x3e8, SPLTTY, 5, 0, 0, comintrs,
                                         (caddr_t) 0x3e8, 8, 0, 0, 0},

Change the 5 after SPLTTY to be something else, and then edit the SB
entry to use IRQ 5, and you should be set.

IRQ 10 is almost certainly a safe bet because only 16-bit cards can
use it.  The problem is that the original Sound Blaster didn't support
IRQ 10, so some older SB software under DOS won't look for your sound
card there.  This may be a problem if you still intend to run DOS
games and such that support the original Sound Blaster.  Check out
your favorite games and such before committing to this IRQ.

IRQ 2 is just confusing.  It is also probably the best choice.  If you
are interested in understanding the whole issue, read on.  If you just
want to get your card working, accept the fact that IRQ 2 on the bus
is really IRQ 9 to Unix. Set your jumper to "IRQ 2", and configure the
kernel (autoconf.c) to be IRQ 9.  You can Jump down to CONFIGURING.

Here's the full scoop: On a 16-bit bus, they decided to add more
interrupts.  (The original 8-bit bus PCs had eight.)  To do this, they
added another identical Parallel Interrupt Controller (PIC) chip,
giving them eight more input lines.  The odd part is that the second
PIC signals the first PIC chip when an interrupt comes in on the
16-bit side.  This interrupt signal is sent into IRQ 2 on the first
PIC chip whenever an interrupt comes in on IRQ lines 9 through 15.
This means that, in an AT, your cards can not really send an IRQ 2;
only the second PIC can do that.  (This whole concept is suitably
called "cascading" the PIC chips.)  Think about all this until it
makes sense, and then go on.

To keep things compatible, the wire on the bus that used to be IRQ 2
is not really connected to IRQ 2 on the first PIC chip anymore.  It
can't be, because the second PIC chip needs that IRQ for itself.  Now,
they decided to keep that line on the bus useful, and rewired it to be
IRQ 9, which is the first interrupt line on the *second* PIC chip.
So, the wire on the bus that used to be IRQ 2, is now really IRQ 9,
and the real IRQ 2 is used by the second PIC chip.  The two chips give
you a total of 16 lines, but since one is used by the second chip,
there are only IRQ lines 1 through 15 available on the bus.

Now, in DOS, there is a vector table in memory to tell what to do
about each interrupt.  DOS sets this up so that IRQ 9 does what IRQ 2
would do on an 8-bit machine.  So, Creative Labs labeled the jumper
IRQ 2 to keep from confusing people, and all the old DOS software will
find the card when it looks at IRQ 2.  That's about it.

The moral of the story is that it's really IRQ 9 at the hardware
level, and Unix requires that it be called by its true number, which
is 9.  IRQ 2 is not available to kernel driver.  For this reason, set
the jumper to "IRQ 2" and tell the kernel (define SB_IRQ down in
autoconf.c) that the card is at IRQ 9.  And then just nod your head in
understanding when DOS software says that it found your card at IRQ 2.
 

CONFIGURING THE KERNEL:
----------------------
If you have never recompiled your kernel before, you will certainly
want to do this before even thinking about installing this driver.
First work all the glitches out of a straight default build of the
kernel, then start adding things.  If you have little experience at
remaking your kernel, and get stuck, I will try to help.  Send Email,
of course.

I am going to explain things as simply as I can.  If you are a Kernel
Guru, please don't feel offended or anything, I just want to try to
make it simple for as many people as possible.

After verifying that you can recompile the normal kernel and produce
something usable, you will need to edit several configuration files.
Diffs don't seem practical for this, so I have just included the
necessary additions as they are.

I'm not sure how varied the specifics are among 386 BSD's, but if you
get the general idea, hopefully you can figure out how to make things
click on your system.  Of course, when you figure it out, send me mail
so I can tell people how to put it on System X.  Here we go!


----- File src/conf/MASTER.i386.local:

This file selects which options get compiled into the kernel.
The easiest thing to do is edit the line that looks like:

#  BINARY    = [debug mach gcc unix small MSTD nfs WS fp pseudomouse]

To make it look like:

#  BINARY    = [debug mach gcc unix small MSTD nfs WS fp pseudomouse sb]

This adds the Sound Blaster option to the BINARY configuration.
Then add the device description itself to the end of this same file:

pseudo-device   sb              # <sb>

OK, Next file...


----- File src/conf/files.i386:

This tells which files are used for which devices.  You need to list
the pathname of the Sound Blaster driver code.  If your sb_driver.c
and supporting files are in the directory src/local, it would look
like this:

local/sb_driver.c               optional sb device-driver

The end tags tell that it is an optional device driver given the short
name "sb" for use elsewhere in configuration.


----- File src/i386at/conf.c:

Add the following code right in the middle of all the other redundant
blocks that look a lot like it.  I put mine right before the "wt.h"
driver.  Specific position doesn't matter, just in the area with all
the rest.


#include "sb.h"                 /* Sound Blaster */
#if     NSB > 0
int     sb_open (), sb_close (), sb_ioctl (), sb_read (), sb_write ();
#else   NSB > 0
#define sb_open         nulldev
#define sb_close        nulldev
#define sb_ioctl        nulldev
#define sb_read         nulldev
#define sb_write        nulldev
#endif  NSB > 0


Further down in the same file, there is a large array called cdevsw[].
This contains all the functions to call for various system calls like
open, close, read, write, ioctl, etc..

CMU has reserved all the major numbers up to 29, so you can make yours
the next one.  The position in this array will be the major number you
give to your devices when you 'mknod' them in /dev.  So, don't just
slap it anywhere in the structure, but be sure to put it at the end.
On my system, this means that the SB device will have major number 30.
Remember this major number, you will need it for creating the entries
in /dev.

Add these lines just within the closing brace of the cdevsw structure:

        sb_open,        sb_close,       sb_read,        sb_write,       /*30*/
        sb_ioctl,       nodev,          nodev,          0,
        seltrue,        nodev,
 

----- File src/i386at/autoconf.c:

Again, add this block in with all the others that look like it.  This
tells the kernel what functions to call on an interrupt, and such.

#include <sb.h>                 /* Sound Blaster */
#if NSB > 0
extern struct isa_driver        sb_driver;
extern int                      (*sb_intrs[])();
#endif NSB

Also, you need to add this to the struct isa_dev Devsp[] declaration
in autoconf.c.  Edit the IO_PORT and IRQ as necessary.  See the above
section if you aren't sure what to use for the PORT, or IRQ values.

#if NSB > 0
#define SB_IO_PORT 0x220
#define SB_IRQ     9
        {&sb_driver, 0, -1, 0, 0, (caddr_t)SB_IO_PORT, SPL1, SB_IRQ, 0, 0,
           sb_intrs, (caddr_t)SB_IO_PORT, 24, 0, 0, 0},
#endif NSB

Again, just slap that in with all the other similar structures.

-----

Ok, that's it for editing files.  Now install sb_driver.c and
sb_regs.h into whatever directory you named earlier (like src/local),
where the Makefile can find them.  Also, put sblast.h into
/usr/include/i386at where everyone can get to it.  It has all the defs
needed for user programs to use the device, and the driver itself
looks for it there.

So, give it a whirl and see how far 'make' gets!

I hope it goes smoothly, but if it doesn't, send Email.

Once you have booted your new kernel, somewhere in the boot messages
that fly by, it should say "Sound Blaster found" and list the I/O
settings.  If you see this, then things are in order!

Now you have to make your device files.  First, edit the
MAKEDEVS.sblast script to reflect the major number you got earlier.
Set the variable "major" to be the right number.
Become root and run the script to make all the device entries in /dev.

To test your new device, compile the programs in user_progs, and run
"mixer" to look at the current settings.  If things look OK, try
setting the DSP speed to, say 45454 (mono) by running
$ cdsp 45454 -mono

If that works too, be daring and celebrate your new driver
with something like this: 

$ cdsp 
$ cat /vmunix >/dev/sb_dsp

If you hear the worst noise ever, Congratulations!
Go get some unsigned-byte soundfiles and play away, or make your own with:

$ cat /dev/sb_dsp > soundfile

Good Luck & Happy Hacking!
-Steve

Steve Haehnichen
E-Mail: shaehnic@ucsd.edu
