Coda for Windows 95
-------------------

========
WARNING:
========
The software provided to run Coda on Windows 95 is an early pre-alpha
snapshot, made available to those interested.  Coda runs kernel level
code and priviliged processes which can cause damage to your system.
Backup all data before playing with Coda.

====================================
Credits & History (Windows specific)
====================================

Coda was developed at Carnegie Mellon University in the group of
M. Satyanarayanan.  Numerous people contributed to Coda, see the
CREDITS file for details.

Michael Callahan ported Coda to Windows 95.  Most importantly he wrote
the Windows 95 kernel support for DPMI (Dos Protected Mode Interface)
sockets, memory mapping as well as Coda specific file system code.  He
used the djgpp compiler and libraries, and extended these to exploit
the new memory mapping and socket kernel code.  All compilation is
done with a Linux to DOS cross compiler.  The end result was a state
of affairs where the Coda client could list some directories and read
and write files, i.e. almost everything worked, but much debugging and
extending remains to be done.

Peter Braam assisted in the debugging, adapted the Coda code to
accomodate Michael's changes most easily. He ported the server and
utilities to Win32 (these run on both Windows NT and Windows 95 but
need to be differently configured for each platform).  Jay Kistler
discovered the correct memory settings for the servers and debugged
problems with memory mapping and rvm. Michael was helpful at throughout.
Here the cygwin POSIX library for Windows 32 was used and again cross
compilation from Linux was exploited.  As yet there is no client for
Windows NT.

Peter put all the releases together and made packages for the debugger
and cross compilers.


===============
Short rationale
===============

Why DOS applications??  It would seem more straightforward to
implement the Coda client cache manager, a user level program named
Venus, as a Win32 application.  Sadly on Windows 95 we ran into the
following (fairly well known) problem.  When a user application calls
a Win32 file system call, the application may acquire a mutex in a
win16 system dll.  The request should reach the kernel, and make its
way up to Venus.  Venus is then unable to service the request because
it cannot grab the mutex. Deadlock results.

Implementing all of Venus as a kernel level cache manager seemed an
invitation for disaster.  Instead, by running the cache manager in a
virtual DOS machine, as a DOS Protected Mode Interface application,
one can bypass these problems, since such applications do not share
the Windows dynamic libraries which gain the mutex.  The price of
following this path is high.  There was no freely available socket
support for such DPMI applications and no memory mapping support.
These are provided by Michaels VXD's and standard library calls are
now incorporated in the DJGPP toolchain.


============================
BUILDING Coda for Windows 95
============================

No binairies are included at this point.  You'll have to build
everything from scratch.


1) Building the user level Code

What do you need: 

a) for the user level code: a Linux machine with a few 100M of free
space.

download the tool chains made available under:
ftp://ftp.coda.cs.cmu.edu/pub/tools/{win95,nt,djgpp,cygwin}

You need the rpms for:
- djgpp package
- djgpp-win95ext
- cygwin
- libdb-nt
- gdb-djgpp a "remote debugging" environment for DPMI applications. 

It is highly recommended to set up Samba to share Linux generated
binaries with the Windows box.

b) for the VXD's: Visual C++ 5.0 (Internet Explorer), MS assembler 6.11,
the Win95 DDK (comes with professional MSDN).  Also you need to download a
collection of header files vxdtdi.zip for networking from 
ftp.microsoft.com://developr/drg/WinSock/MS-Extensions/VXDTDI.ZIP.

Note that the 95DDK needs the VC2.0 linker, which on the 95DDK in the 
directory MSVC20 (also get the files Link.err and DBI.DLL, that will be needed
by the linker). You'll also need the latest MS assembler 6.11 which 
is on the 95DDK in the directory MASM611C.
 
The VxD's you will want to build are in:
vc95\95vxds\{mmap,sock,mcstub,mc}

To build sock.vxd you'll need the header files provided by microsoft and
can be found in VXDTDI.ZIP.

You'll have to learn how to build VxDs, but it can be done from
Developer Studio.
-Change the path of the Linker in all .mak files.
-In the MS-Studio environment (options) add:
  -executable path of the assembler 6.11.
  -include path of the 95DDK (Inc32).
  -lib path of the 95DDK (lib).
  -include path where VXDTDI Headers are.
  -include path of the 95DDK (Block/Inc).

Place the mcstub and mmap VxD's in c:\VxDs (or elsewhere).

The sock and mc vxd's need to go to the place where you install
relay.

(If you fancy finishing off Michael's nice codastart project, make 
sure to let us know! It is not essential for now.)

c) Coda specific source code.
Get the latest tarball of Coda sources.

example:

ftp://ftp.coda.cs.cmu.edu/pub/coda/src/coda-4.6.x.tgz

Also get:

ftp://ftp.coda.cs.cmu.edu/pub/coda/src/vc95.zip

You can rebuild Venus with ./configure --target=win95; make coda

and the client utilities and server with
./configure --target=winnt (the Venus built here is unusable on Win95).


====================
Manual Configuration
====================

a) Configuration work for the VxDs

Edit C:\windows\system.ini and add

device=c:\VxDs\mcstub.vxd
device=c:\VxDs\mmap.vxd

in the [386Enh] section. 

b) Coda binaries: you need at the minimum:
venus.exe, relay.exe, mount.exe, umount.exe

They are all built by gcc and reside under djgpp or coda-src/venus. 

c)
Make sure you have a directory tree:

c:\usr\coda\{etc,venus.cache,spool}

Also edit: 
c:\usr\coda\etc\vstab
and edit the server if you do not want to contact the testserver

=============
Starting Coda
=============

1. start relay
c:\coda-4.5.1\bin\relay

This will load the socket and mc VxDs.

2. initialize Venus
c:\coda-4.5.1\bin\venus -child

3. start venus (first time -- very few cache files just to play)
c:\coda-4.5.1\bin\venus -init -cf 500 
Wait a little bit.

4. mount N:
Coda is mounted on the N: drive and should but doesn't work. 

To restart venus, do not give any flags.
When you unmount coda with "unmount.exe n:" then you have to start relay.exe
again.

=========
Debugging
=========

Michael also built a remote debugging target for gdb.  From the
comfort of your Linux box you can step through the Coda code.

Get the gdb-djgpp rpm from 
ftp://ftp.coda.cs.cmu.edu/pub/tools/{win95,nt,djgpp,cygwin}

First run gdbserver :4711 your-prog your-arg on in the DOS command
windows on Windows 95.  Then fire up dos-gdb and attach to the server
with target remote dos.host:4711 (4711 is a TCP port number).  You can
set break points, step and examine (try prepending _ if
necessary). You cannot stop programs.  It works for C and C++ compiled
with the GNU C compiler gcc.

====================================
To do, aka missing features and bugs
====================================

Lots and lots:

1. Readdir is broken and dir doesn't work. That's a bummer.
2. We badly need "Potemkin" a testing tool for kernel code (under utils)
3. An mpr dll is needed, otherwise MsWord etc cannot open Coda files.
4. Something is wrong with lwp (test doesn't work, something is maybe 
wrong with select)
5. Test it, debug it, make it better!


Good luck.  Let us know if you cannot mount the Coda filesystem.


- Peter Braam -
braam@cs.cmu.edu
-------------------------------------------------------------
This is for the future... when it works sort of:

Nothing like this now exists.

===========
To install:
===========

Fetch
ftp://ftp.coda.cs.cmu.edu/pub/coda/win95/coda-client-4.5.1.exe
ftp://ftp.coda.cs.cmu.edu/pub/coda/win95/dpmi-win95ext-2.0.1.exe

Run the installer: it installs the following (all of which are needed):

From the DPMI extender package:
vxd's in C:\dpmi95
 mmap.vxd
 sock.vxd

All further files are installed by the coda-client package:

a) vxd's: in C:\coda-4.5.1\bin
 mc.vxd
 mcstub.vxd

b) DOS-type user level code:

 - mount utilities in C:\coda-4.5.1\bin
 mount.exe
 relay.exe
 unmount.exe
 
 - the cache manager in C:\coda-4.5.1\bin
 venus.exe
 
c) Win32 console applications C:\coda-4.5.1\bin
 
The install script adds the vxd to your c:\windows\win.ini file and
installs a coda configuration directory: 
c:\usr\coda
with a default layout.