src/TechNotes-WIN9X

   1 Win9x AFS Client: Technical Notes
   2 ---------------------------------
   3
   4 This file gives a technical overview of the Win9x AFS client and describes
   5 the main differences from the NT client.
   6
   7
   8 Overview
   9 --------
  10
  11 The Windows 9x client is based on the Windows NT/2000 client.  Like the
  12 NT client, it exports AFS through an SMB interface.  Programs access AFS
  13 files by mounting AFS submounts as SMB shares and using the built-in
  14 Windows SMB client to communicate with the AFS client.  The AFS client
  15 acts as an SMB server.  It runs entirely at user level.
  16
  17 DOS box implementation and VXD's
  18 --------------------------------
  19
  20 The main program of the Win9x client, afsd.exe, is implemented as a
  21 32-bit DOS program.  It is compiled using the DJGPP compiler and runs in
  22 a Windows 9x DOS virtual machine.  This approach was necessary to avoid
  23 a well-known deadlock problem in Windows 9x when the kernel calls up
  24 to a user-level Win32 daemon: the original requesting program grabs the
  25 Win16Mutex before entering the kernel.  The request is then passed up to
  26 the daemon, who attempts to service it using network or file I/O calls.
  27 These calls also attempt to obtain the Win16Mutex, which is still being
  28 held by the original requester, so there is a deadlock.
  29
  30 To avoid this problem, the daemon runs in a DOS box.  I/O calls from
  31 a DOS program do not attempt to obtain the Win16Mutex, so the deadlock
  32 is avoided.  This approach was discovered by the Coda team at Carnegie
  33 Mellon University and used to implement a Win9x version of their client.
  34 The Win9x AFS client uses the same approach.  It also uses the Coda team's
  35 SOCK.VXD which was written to provide network functions to a DOS program.
  36 Sockets functions which call SOCK.VXD were added to the DJGPP library.
  37
  38 For more information about the Coda team's approach to this problem, see
  39 their paper from Usenix 1999:
  40 http://www.cs.cmu.edu/afs/cs/project/coda/Web/docdir/freenix99.pdf
  41
  42 Note that the AFS client also requires the Coda team's MMAP.VXD.  We are
  43 not actually calling this VXD, but afsd crashes if it is built without
  44 it (i.e., by building with dos-gcc -bw95 instead of -bmmap).  Solutions to
  45 this problem welcomed..
  46
  47 Netbios functions
  48 -----------------
  49
  50 The Windows AFS clients communicate with user applications using the
  51 SMB protocol, as described above.  SMB communication is done using the
  52 Netbios interface.  In Win32, there is a built-in function Netbios()
  53 which accomplishes this.  In a DOS program, however, this function is
  54 unavailable.  However, Netbios functionality is available in the BIOS
  55 by calling interrupt 0x5c.  The NCB (Netbios Control Block) and data
  56 buffer must be in conventional DOS memory, i.e., below 1 MB.  This memory
  57 can only be accessed in DJGPP by using the DOS memory access functions:
  58 dosmemget(), dosmemput(), _farpeekX() and _farpokeX().  The Win9x client
  59 uses a separately-allocated DOS memory buffer and copies data to and from
  60 DOS memory for network communication.
  61
  62 Functions were also added to LWP's iomgr.c to check for the completion
  63 of Netbios requests.  The IOMGR now checks for NCB completion in addition
  64 to checking for timer expiration, signal delivery, and performing select()
  65 on file descriptors.
  66
  67 See the new files: netbios95.c, dosutils95.c, and the various changes
  68 (marked by "#ifdef DJGPP") to smb.c in WINNT/afsd.  Also see lwp/iomgr.c.
  69
  70 Thread functions
  71 ----------------
  72
  73 Unlike the NT client which uses Win32 thread and locking functions,
  74 the Win9x client uses the LWP package from the AFS source distribution.
  75 An interface layer was added to allow NT and Win9x to make the same calls.
  76 For example, thrd_Create() is now used to create a thread.  In NT, this
  77 is just a macro to the Win32 function CreateThread().  In Win9x, it is a
  78 function which calls the LWP function LWP_CreateProcess().  See the new
  79 files osithrd95.c, osithrd95.h, and osithrdnt.h in WINNT/client_osi.
  80
  81 Configuration parameters
  82 ------------------------
  83
  84 In DJGPP, it is not feasible to access the system registry, which is
  85 where the NT client stores its configuration info.  For the Win9x client,
  86 the Unix approach is followed instead: the local cell is in a file called
  87 "ThisCell", cache configuration is in a file called "cache.info", and
  88 the cell database is stored in "CellServDB" instead of "afsdcell.ini".
  89 Many parameters are passed via the command line to afsd.exe and are
  90 processed just like the Unix clients.
  91
  92 See the new files afsd_init95.c and afsd95.c in WINNT/afsd.
  93
  94 Authentication
  95 --------------
  96
  97 In the functions SetToken() and GetToken(), the NT client sends and
  98 receives the session key using a separate RPC which should use encryption,
  99 rather than including the session key in the pioctl packet.  The Win9x
 100 version avoids this RPC and puts the session key back into the pioctl.
 101 This should not be a security issue on Win9x since it is a single-user
 102 machine.  (The pioctl packet will not be visible externally.)  See files
 103 WINNT/afsd/cm_ioctl.c and auth/ktc_nt.c.
 104
 105 Persistent (disk) caching
 106 -------------------------
 107
 108 Disk caching support was added for the 9x client.  This has barely been
 109 tested and is still very experimental!  In addition, there are numerous
 110 performance issues.  It relies on the fact that LWP is a non-preemptive
 111 threads package, so no locking is done to protect shared data structures.
 112 In addition, it uses synchronous I/O to read and write disk files.  Since
 113 LWP is a user-level threads package, any calls to normal I/O system calls
 114 like read() or write() will block the entire process.  One better approach
 115 would be to add support for local disk file descriptors to the select()
 116 call used by IOMGR, and then to use IOMGR_Select to enqueue I/O requests
 117 to the disk.  Currently, the select() function supports only sockets.
 118
 119 It should be fairly easy to adapt this code for the NT client.  See the
 120 implementation in WINNT/afsd/cm_diskcache95.c.  To enable this code,
 121 define DISKCACHE95 in WINNT/afsd/Makefile.djgpp.
 122
 123 Utility programs
 124 ----------------
 125
 126 The utility programs, such as klog.exe and fs.exe, are Win32 programs and
 127 are built using the Microsoft compiler.  Changes to the code for these
 128 files are marked by "#ifdef AFS_WIN95_ENV".
 129
 130 GUI interface
 131 -------------
 132
 133 The Win9x client does not use the NT configuration GUI programs in
 134 client_creds and client_cpa (Control Panel Applet.)  It uses a separate
 135 GUI program called WinAfsLoad.exe in WINNT/win9xpanel.  This program can
 136 start afsd.exe and keep track of submounts and token expiration.
 137
 138 The Explorer shell extension, which allows right clicking on a file
 139 in Windows Explorer to get an AFS submenu, is supported in Win9x.
 140 See WINNT/client_exp.
 141
 142 Integrated logon
 143 ----------------
 144
 145 Integrated logon is not supported in the 9x client.
 146
 147 Known issues
 148 ------------
 149
 150 1) The Microsoft linker LINK386.exe causes a deadlock when attempting to
 151 create an executable on an AFS filesystem.  Somehow, the linker appears
 152 to be preempting the entire machine so afsd.exe cannot run to service
 153 requests.  Solutions to this problem eagerly sought!  (This problem does
 154 not seem to occur with the Win9x Coda client.)