import winsup-2000-02-17 snapshot

winsup/cygwin/ROADMAP

@@ -0,0 +1,129 @@
+
+			    WINSUP ROADMAP
+
+The purpose of this document is to give the briefest overview of how
+the various parts of cygwin work together and where everything can be
+found.  The intended audience is people developing the cygwin dll
+itself.  Comments to dj@cygnus.com.
+
+=== cygwin1.dll source files
+
+- overhead
+.h	winsup autoload debug external shared sync
+.cc	assert dcrt0 debug external init ntea registry security
+	shared smallprint strace sync
+.din	cygwin
+.rc	winver
+.sgml	external shared
+
+- processes
+.h	sigproc
+.cc	exec fork pinfo resource signal sigproc spawn wait
+
+- signals
+.cc	exceptions window
+
+- files and I/O
+.h	delqueue fhandler path select
+.cc	delqueue dir fhandler* hinfo path pipe select tty
+.sgml	hinfo path
+
+- common unix functions
+.h	dll_init tz_posixrules
+.cc	dlfcn dll_init environ errno fcntl flog grp ioctl localtime
+	malloc passwd scandir strsep syscalls sysconf syslog termios
+.c	longjmp setjmp
+.sgml	dll_init
+
+- unix emulation
+.cc	heap mmap net times unifo uname
+
+
+--- if MT_SAFE
+.h	thread
+.cc	pthread thread
+
+--- from other places
+regex/*
+../libiberty/{random,strsignal}
+../newlib/* (libc)
+
+=== libcygwin.a source files
+
+libccrt0.cc
+libcmain.cc
+dll_entry.cc
+dll_main.cc
+getopt.c
+
+=== gmon (profiling, -pg)
+
+gcrt0.c
+gmon.c		gmon.h
+mcount.c
+profil.c	profil.h
+
+=== entry points
+
+- normal cygwin program
+
+newlib/libc/sys/cygwin/crt0.c has mainCRTStartup() and calls cygwin_crt0()
+
+libccrt0.cc has cygwin_crt0() and calls dll_crt0()
+
+dcrt0.cc - has dll_crt0()
+
+Note: dll_init.cc has nothing to do with initializing the cygwin dll.
+It initializes the dlls you have dl_open'd.
+
+- cygwin-built dll
+
+dll_entry.cc - has a macro for wrapping your dll startup function
+	(equivalent of DllMain()) in such a way that you get your
+	cygwin environment set up automatically when your dll is
+	loaded.
+
+dll_main.cc - has empty DllMain() in case you don't have your own
+
+- manually loading cygwin1.dll
+
+init.cc - has dll_entry() which is called by the OS when the dll is
+	loaded.  It doesn't do much except note if you linked
+	cygwin1.dll or are manually loading it.
+
+=== About "fhandlers"
+
+An fhandler is a file type handler.  This is where the unix device
+emulation happens.
+
+hinfo.cc maps posix file descriptors to a table of file handlers (type
+fhandler) in the dll.  It's mostly concerned with managing the table
+of descriptors (open, dup, fork, select).  Most of the posix I/O
+system calls (syscalls.cc) use the hinfo table to call the right
+fhandler directly.
+
+fhandler.cc is the base class; specific types are derived as
+appropriate (see fhandler.h).  hinfo.cc is in charge of selecting and
+creating a suitable fhandler when you open a file.  path.cc handles
+emulated files in /dev (like /dev/null) by returning an FH_* value
+from get_device_number (which hinfo.cc calls in hinfo::build_fhandler).
+
+Note: if you're looking for read() and write(), they call _read() and
+_write() in syscalls.cc.  The non-underscored ones are in
+newlib/libc/syscalls and just call the underscored ones.
+
+=== How "fork" works
+
+It all starts in fork() in fork.cc.
+
+Set up a pid in the shared memory area for the new child.  Use
+setjmp() to capture state.  First time (parent), set up some stuff and
+use CreateProcess to run a second copy of the same executable.  The
+second copy will note in the shared memory area that it's a fork, and
+do the longjmp.  They sync up and the parent copies all it's program
+memory to the child's address space.  There's also code to reload
+dlls, map shared memory and mmap'd files, etc.
+
+Handling the special startup for the child is done in dcrt0.cc in many
+places.  This case is triggered by a special StartupInfo structure
+that's passed from the parent to the child in CreateProcessA.