1 files changed, 158 insertions, 0 deletions
diff --git a/winsup/cygwin/DevDocs/how-signals-work.txt b/winsup/cygwin/DevDocs/how-signals-work.txt
new file mode 100644
index 000000000..09d7d0aa5
--- /dev/null
+++ b/winsup/cygwin/DevDocs/how-signals-work.txt
@@ -0,0 +1,158 @@
+Contributed by Christopher Faylor
+
+[note that the following discussion is still incomplete]
+
+How do signals work?
+
+On process startup, cygwin starts a secondary thread which deals with
+signals.  This thread contains a loop which blocks waiting for
+information to arrive on a pipe whose handle (sendsig) is currently
+stored in _pinfo (this may change).
+
+Communication on the sendsig pipe is via the 'sigpacket' structure.
+This structure is filled out by the sig_send function with information
+about the signal being sent, such as (as of this writing) the signal
+number, the originating pid, the originating thread, and the address of
+the mask to use (this may change).
+
+Any cygwin function which calls a win32 api function is wrapped by the
+assembly functions "_sigfe" and "_sigbe".  These functions maintain a
+cygwin "signal stack" which is used by the signal thread to control
+handling of signal interrupts.  Cygwin functions which need to be
+wrapped by these functions (the majority) are labelled by the SIGFE
+option in the file cygwin.din.
+
+The cygwin.din function is translated into a standard cygwin.def file by
+the perl script "gendef".  This function notices exported cygwin
+functions which are labelled as SIGFE and generates a front end assembly
+file "sigfe.s" which contains the wrapper glue necessary for every
+function to call sigfe prior to actually dispatching to the real cygwin
+function.  This generated file contains low-level signal related
+functions: _sigfe, _sigbe, sigdelayed, sigreturn, longjmp, and setjmp.
+
+The signal stack maintained by sigfe/sigbe and friends is a secondary
+shadow stack.  Addresses from this stack are swapped into the "real"
+stack as needed to control program flow.  The intent is that executing
+cygwin functions will still see the same stack layout as if they had
+been called directly and will be able to retrieve arguments from the
+stack but will always return to the _sigbe routine so that any signal
+handlers will be properly called.
+
+Upon receipt of a "non-special" (see below) signal, the function
+sigpacket::process is called.  This function determines what action, if
+any, to take on the signal.  Possible actions are: Ignore the signal
+(e.g., SIGUSR1), terminate the program (SIGKILL, SIGTERM), stop the
+program (SIGSTOP, SIGTSTP, etc.), wake up a sigwait or sigwaitinfo in a
+targetted thread, or call a signal handler (possibly in a thread).  If
+no thread information has been sent to sigpacket::process, it determines
+the correct thread to use based on various heuristics, as per UNIX.  As
+per linux, the only time a handler is called in a thread is when there
+is some kind of fault like SIGSEGV, SIGILL, etc.  Signals sent via the
+UNIX kill() function are normally sent to the main thread.  Ditto
+signals sent as the result of pressing tty keys, like CTRL-C.
+
+Signals which stop a process are handled by a special internal handler:
+sig_handle_tty_stop.  Some signals (e.g., SIGKILL, SIGSTOP) are
+uncatchable, as on UNIX.
+
+If the signal has an associated signal handler, then the setup_handler
+function is eventually called.  It is passed the signal, the address of
+the handler, a standard UNIX sigaction structure, and a pointer to the
+thread's "_cygtls" information.  The meat of signal processing is in
+setup_handler.
+
+setup_handler has a "simple" task.  It tries to stop the appropriate
+thread and either redirect its execution to the signal handler function,
+flag that a signal has been received (sigwait) or both (sigpause).
+
+To accomplish its task, setup_handler first inspects the target thread's
+local storage (_cygtls) structure.  This structure contains information
+on any not-yet-handled signals that may have been set up by a previous
+call to setup_handler but not yet dispatched in the target thread.  If this
+structure seems to be "active", then setup_handler returns, notifying it's
+parent via a false value.  Otherwise processing continues.
+
+(For pending signals, the theory is that the signal handler thread will
+be forced to be rerun by having some strategic cygwin function call
+sig_send with a __SIGFLUSH argument.  This causes the signal handler to
+rescan the signal array looking for pending signals.)
+
+After determining that it's ok to send a signal, setup_handler will lock
+the cygtls stack to ensure that it has complete access.  It will then
+inspect the thread's 'incyg' boolean.  If this is true, the thread is
+currently executing a cygwin function.  If it is false, the thread is
+unlocked and it is assumed that the thread is executing "user" code.
+The actions taken by setup_handler differ based on whether the program
+is executing a cygwin routine or not.
+
+If the program is executing a cygwin routine, then the
+interrupt_on_return function is called which causes the address of the
+'sigdelayed' function to be pushed onto the thread's signal stack, and
+the signal's mask and handler to be saved in the tls structure.  After
+performing these operations, the 'signal_arrived' event is signalled, as
+well as any thread-specific wait event.
+
+Since the sigdelayed function was saved on the thread's signal stack,
+when the cygwin function returns, it will eventually return to the
+sigdelayed "front end".  The sigdelayed function will save a lot of
+state on the stack and set the signal mask as appropriate for POSIX.
+It uses information from the _cygtls structure which has been filled in
+by interrupt_setup, as called by setup_handler.  sigdelayed pushes a
+"call" to the function "sigreturn" on the thread's signal stack.  This
+will be the return address eventually seen by the signal handler.  After
+setting up the return value, modifying the signal mask, and saving other
+information on the stack, sigreturn clears the signal number in the
+_cygtls structure so that setup_handler can use it and jumps to the
+signal handler function.  And, so a UNIX signal handler function is
+emulated.
+
+The signal handler function operates as normal for UNIX but, upon
+return, it does not go directly back to the return address of the
+original cygwin function.  Instead it returns to the previously
+mentioned 'sigreturn' assembly language function.
+
+sigreturn resets the process mask to its state prior to calling the
+signal handler.  It checks to see if a cygwin routine has set a special
+"restore this errno on returning from a signal" value and sets errno to
+this, if so.  It pops the signal stack, places the new return address on
+the real stack, restores all of the register values that were in effect
+when sigdelayed was called, and then returns.
+
+Ok.  That is more or less how cygwin interrupts a process which is
+executing a cygwin function.  We are almost ready to talk about how
+cygwin interrupts user code but there is one more thing to talk about:
+SA_RESTART.
+
+UNIX allows some blocking functions to be interrupted by a signal
+handler and then return to blocking.  In cygwin, so far, only
+read/readv() and the wait* functions operate in this fashion.  To
+accommodate this behavior, a function notices when a signal comes in and
+then calls the _cygtls function 'call_signal_handler_now'.
+'call_signal_handler_now' emulates the behavior of both sigdelayed and
+sigreturn.  It sets the appropriate masks and calls the handler,
+returning true to the caller if SA_RESTART is active.  If SA_RESTART is
+active, the function will loop.  Otherwise it will typically return -1
+and set the errno to EINTR.
+
+Phew.  So, now we turn to the case where cygwin needs to interrupt the
+program when it is not executing a cygwin function.  In this scenario,
+we rely on the win32 "SuspendThread" function.  Cygwin will suspend the
+thread using this function and then inspect the location at which the
+thread is executing using the win32 "GetThreadContext" call.  In theory,
+the program should not be executing in a win32 api since attempts to
+suspend a process executing a win32 call can cause disastrous results,
+especially on Win9x.
+
+If the process is executing in an unsafe location then setup_handler
+will (quickly!) return false as in the case above.  Otherwise, the
+current location of the thread is pushed on the thread's signal stack
+and the thread is redirected to the sigdelayed function via the win32
+"SetThreadContext" call.  Then the thread is restarted using the win32
+"ResumeThread" call and things proceed as per the sigdelayed discussion
+above.
+
+This leads us to the sig_send function.  This is the "client side" part
+of the signal manipulation process.  sig_send is the low-level function
+called by a high level process like kill() or pthread_kill().
+
+** More to come **