winsup roadmap

[DJ Delorie]

I've been working on (a little at a time) a "roadmap" to the
cygwin/winsup sources.  Attached is a preliminary version for review
and comments.  Note that the intention is to give just enough overview
of which files do what, that a programmer will be able to find where
things are in the sources, kind of a starting point for understanding
the cygwin/winsup sources.

DJ


			    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.