This file gives instructions on installing a csound file system on a
UNIX machine.  

Install a pseudouser who will be the owner of all
the sound file programs.  At CARL, this pseudouser is named disk,
for no particular reason.  All csound programs
run in Set-User-Id mode so as to guarantee the integrity of data.  
Put him in the sys group (optional, but convenient).

Then prepare the appropriate target UNIX directories and
raw devices for the csound
system to manage as a sound file system.  A minimum of one small,
regular UNIX directory and one raw disk partition is required.  
The UNIX directory is typically 2 cylinders, the raw partition is
usually the rest of the disk.
If more than one csound filesystem is to be put up, the directories 
are named /snd and /snd1, etc. 
It is possible to split a disk between a csound file system and a regular
UNIX filesystem used for other purposes, but best results occur when
a whole disk is devoted to this one thing.  For instance, at CARL,
we have csound systems on a CDC 9766 and three RA81's.  The csound
filesystem on the CDC is named /snd.  The CDC is managed by the up driver.
We mount /snd on /dev/up?e, and use the raw partition /dev/rup?f.
For example, the partition table for our up device is:

/*	sectors, offset			       */
	16416,	0,	/* A=cyl   0 thru  26  */
	34048,	27,	/* B=cyl  27 thru  82  */
	249280,	2,	/* C=cyl   2 thru 411  */
	249888,	412,	/* D=cyl 412 thru 822  */
	1216,	0,	/* E=cyl   0 thru   1  */
	499168,	2,	/* F=cyl   2 thru 822  */
	449920,	83,	/* G=cyl  83 thru 822  */
	500384,	0,	/* H=cyl   0 thru 822  */

The directories will be used to contain text
files with descriptive and pointer information for where on the raw
devices a particular sound resides.  These text files are called Sound 
Descriptor Files (SDF) and the directory containing them is called
the SDF directory.  (Note the use of a slightly confusing nomenclature:
when the descriptive data is in a file, it is called a Sound Descriptor
File.  When that data has been read into the memory of a process,
it is called a Sound File Descriptor (SFD).)

Note: the SDF directories
must be mounted so as to be subdirectories of the root ( / ) directory.
The modes of the csound file directory and device
at CARL as shown by ls -ld are:

    drwxrwxr-x 8 disk        224 Sep  3 17:11 /snd
    crwxrwxr-x 1 disk     13, 13 Sep  3 15:27 /dev/rup0f

The idea is that only "approved" csound
programs that run set-user-id to disk
can access files on /snd.  These files record the location and attributes
of raw sample data on /dev/rup0f.  Non-setUID programs can still access
the raw data for reading, but only approved programs can create new
files or manipulate the free list, etc.

Standard practice is to make both the SDF directory and its
corresponding raw device reside on the same physical storage medium,
so that whithersoever goes one, likewise goes the other.
In general, the size of the SDF directory need not be large.  Since the
minimum size of a sound file is typically
1 cylinder, there can only be as many files as
cylinders.  The SDF files are small, typically less than 200 bytes.
Allocating a partition of 2 cylinders has proved to be sufficient for
a 450MB drive, or more than 1250 cylinders of raw storage.

Create a text file called /usr/carl/lib/sfstab.  This file behaves
somewhat like /etc/fstab.  The entries are in the format:

<directory>:<raw_device>:<read/write_mode>:<size>:<dev_number>:
	<bytes_per_track>:<lock_file>:<bytes_per_cylinder>

The readwrite mode can be rw, rx, (or wx), or xx, meaning read/write,
read-only, (write-only!), and lastly, no access.  The size is the
number of cylinders in the raw device.  The dev_number has two uses: as
an index into an internal table managed by opensf(3carl) that keeps
statistics about open raw devices, and also by the UNIX driver for
Digital Sound Corp.  System 200 converters documented in ds(4).  The
dev_numbers for successive lines must increase monotonically from 0, and
must agree with the device numbers compiled into the ds driver (if
you have DSC converters).  The value of the macro NSFSYS, 
defined in ?/lib/libsf/libsf.h (the ? refers to the root directory
where you have extracted the CARL sources) must be greater than or
equal to the maximum number of separate
file systems shown in sfstab.  At CARL, sfstab looks like this:

    /snd:/dev/rup0c:xx:384:0:16384:/snd/lock:311296:
    /snda:/dev/rra0f:rw:1246:2:26112:/snda/lock:365568:
    /sndb:/dev/rra1f:rw:1246:3:26112:/sndb/lock:365568:
    /sndc:/dev/rra2f:rw:1246:4:26112:/sndc/lock:365568:
    /snd1:/dev/rup1f:xx:821:1:16384:/snd1/lock:311296:
    /snd2:/dev/rup1f:xx:821:1:16384:/snd2/lock:311296:
    /snd3:/dev/rup1f:xx:821:1:16384:/snd3/lock:311296:
    /snd4:/dev/rup1f:xx:821:1:16384:/snd4/lock:311296:
    /snd5:/dev/rup1f:xx:821:1:16384:/snd5/lock:311296:
    /snd6:/dev/rup1f:xx:821:1:16384:/snd6/lock:311296:
    /snd7:/dev/rup1f:xx:821:1:16384:/snd7/lock:311296:
    /snd8:/dev/rup1f:xx:821:1:16384:/snd8/lock:311296:
    /snd9:/dev/rup1f:rw:821:1:16384:/snd9/lock:311296:

We have three RA81 disks permanently mounted as /snda, /sndb
and /sndc, and one CDC9766 with many removable packs mounted
one at a time as /snd1, /snd2, etc.  Note that the permanently 
mounted ones have unique device numbers, while the removable
packs share one number.  Thus, the value of NSFSYS at CARL is 4.
The next field is the size in bytes of a track.  The next field
is the name of a file used for interprocess locking while modifying
files in a filesystem.  The last field is the number of bytes
per cylinder.

Review the file ?/include/carl/sndio.h, and make sure the macros that define
the dimensions of the disks are correct for your system.  
Also check the default file creation
specifications.  Review the rest.  Note, also be sure that you
specify the correct site-specific values in the ds driver, if you
are using them.  Examine file dsc.h in the source directory for
the ds driver.  It is a good idea to review the file
?/include/carl/libsf.h, which contains numerous macros that need to be set.
Also look at ?/include/carl/filesf.h which contains many built-in pathnames.  

To make the system the first time 
copy ?/include/carl/sndio.h to /usr/include/carl.
You must also have installed the ds driver header files dsc.h and
dsreg.h in /usr/include/sys.  
Then compile the csound library in ?/src/lib/libsf via the Makefile.m4
there, and all the
csound programs in directories under ./cmd with the Makefile.m4 in
this directory.
Then in ?/src/lib/libsf, say:
	make install
which will copy ?/src/lib/libsf/libsf.a to /usr/carl/lib. 
Then in ./cmd say
	make install
to move the commands to /carl/bin.
Modify ?/src/lib/libsf/Makefile.m4 and ./cmd/Makefile.m4
if these target directories are not appropriate.  Update Makefile.m4
with the shell script mm.
After installing the programs, if you are using the csh shell,
say 
	rehash.

Compile the program ./cmd/newsfsys/newsfsys.c with its makefile.  Run
the resulting program once for each csound file system being installed,
(/snd, /snd1, etc.)
naming the directory to be used for the descriptor files as an
argument.  You must be the superuser since the program runs chown(1).
This program refers to sfstab, and then creates free storage files and
lock files used for managing the system.

Run the program mksfdir to give the disk user a subdirectory on each
csound filesystem.  For instance,

    % mksfdir /snd/disk

Then write a csound file by saying

    % sndout /snd/disk/test
    (wait a couple of seconds to wait for the opensf() call to succeed)
    [CTRL-D]
    %

Do this for each filesystem.

When this is done, run the command

    % lsf -f /snd/disk/test /snd1/disk/test ...

i.e., do a long form listing of each file created.  The descriptor
files are printed out by this operation.  They should show such
things as file ownership (disk), size (0), sampling rate (49152 at CARL),
etc.  If so, the sound system is installed.

Run mksfdir for each user to be installed on each csound filesystem to
make accounts for the users.

Run the command

	% sfck -A /snd
	% sfck -A /snd1
	.
	.
	.

for each file system.  sfck is the csound equivalent of the UNIX fsck.
While sfck does what it does well, it still has some limitations.
Caution says that if sfck
has to correct something (other than just zapping the free list for
zero-length blocks), it should be run until it runs without errors.

As a precaution, the following is a good idea:  unmount the SDF file
systems.  In the unmounted directories, create the files /snd/MASTERLOCK,
/snd1/MASTERLOCK, ...  Thus, whenever the device is offline, the
csound system will automatically block any attempts to read the file
system or the raw device.  
The contents of the MASTERLOCK files can be a line of text to the effect:
"This csound file system is off line".  The contents of the MASTERLOCK
file is printed on the user console on an access request to a locked
system.  Remount the SDF file systems.

To install the manual pages, copy files in ?/man/manc to /usr/man/manc,
or /usr/man/manl.

The ?/doc/csound subdirectory contains
a tutorial for using some of the csound commands, csound.dgl,
which should be put somewhere people can find it
(at CARL it lives in /mnt/tutorials).
Also in ?/doc/csound is a specification for the csound system, sfspec*,
and a document purporting to tell how to manage a tape dump regimen,
and a description of how to patch the system to avoid bad blocks.

To test the play program, make a sound file as follows:

    % wave | sndout -R16K /snd/disk/test

which will make a 16KHz 1 second sine wave at full amplitude in the file.
(The wave program is in ./cmd/wave).
Then say

    % play /snd/disk/test

and see what happens.  If all goes well, you will be blasted out of
your seat by a full amplitude sine wave at 440Hz.

If you are using removable packs for sound filesystems, edit the
shell scripts mountsf and umountsf to know about your packs, and
install them.

See ?/doc/csound/examp.c for an example usage of the csound library.

NOTES:
1) Two places in the csound system depend on the sequence setuid(geteuid())
after a call to fork() to reset the ownership of the child process
to disk.  Some versions of UNIX do not support this capability (Berkeley
UNIX does).  The two places are ./cmd/mksfdir/system.c and libsf/panic.c.

2) As currently set up at CARL, only the disk pseudo-user has write
permission on the raw storage devices used for sample storage.  Thus,
even though a user can open a csound file in write mode, the first call
to sndo() or fsndo() will fail on write permission.  
This can be changed by giving
write permission to others on the raw storage devices.  The reason we
don't do this at CARL is to try to insure the integrity of the sound samples.
The csound file system does not have a kernel to protect its file
system pointers.  If a user job were to mis-manage memory and overwrite
an in-core sound file descriptor, there is a remote possibility that
it could cause the csound routines
to scribble on the raw disk.  Some solutions to this could be developed, such
as having the write routines verify against the free list before each
transfer is started (since a user job can't write that file directly).
Definitive solutions only await the future.

3) To format and add new removable packs on a VAX:
	a) shutdown the system
	b) run the formatter program described in format(8v).  Note that
		you should try to use the first disk on the first controller
		of the type you are trying to format or else you will have
		to figure out how to specify otherwise!  
		At CARL, this is up0, on sc0, uba0, the rightmost 9766.
		At CARL, to format a 9766 pack, we say:
		>>> L FORMAT
		>>> S 2
		Enable Debugging? 0
		Device to format? up(0,0)
	c) make a filesystem on the formatted pack.  Refer to the
		section above dealing with partition tables.  If you
		must change the partition tables, regenerate your kernel.
		You might want to change the disktab(5) database.
		Then run mkfs.  At CARL, this command is used to
		make a new filesystem on a CDC 9766.
		(The '?' stands for ``put your major device number here.'')
		% /etc/mkfs /dev/up?e 1216 32 19 4096 512 2
		And for a DEC RA81:
		% /etc/mkfs /dev/ra?e 1428 51 14 4096 512 4
		or
		% /etc/mkfs /dev/ra0e 1428 51 14 4096 512 4 5 60 128 t
		if you think you might run out of inodes.
		Refer to mkfs(8) for an explanation of the flags.
	d) make a directory in / to mount the pack on.  For instance, /snd9.
		Make a file in this directory called MASTERLOCK.  The
		presence of this file disables all soundfile programs from
		accessing that directory, thus protecting it from use
		while the actual filesystem is unmounted.
		Check that the permissions of the directory are right, e.g.,
		drwxr-xr-x  2 root     unix          512 Mar  5 12:29 /snd9
	e) mount the disk on the directory.  
		edit /etc/fstab, and add an entry for it:  At CARL:
			/dev/up1e:/snd9:rw:0:0
		Then mount the filesystem.  At CARL:
			% mount /dev/up1e /snd9
	f) make a soundfile system on the mounted UNIX filesystem:
		Edit SFSTAB (at CARL, the file is /carl/lib/sfstab)
		to reflect the added filesystem.  See the discussion above.
		Then run newsfsys:
			% newsfsys /snd9
		Check permissions.  At CARL they should look like this:
		drwxrwxr-x  4 disk     sys           512 Mar  5 12:36 /snd9
	g) make directories for users:
		E.g.,
			% mksfdir /snd9/dgl
	h) edit the mountsf and umountsf scripts to know about the
		new filesystem.
	i) take it out for a spin:
		E.g.,
			% wave | sndout /snd9/dgl/test
			% lsf -f /snd9/dgl/test
