diff --git a/About-Win32-OpenSSH-and-Design-Details.md b/About-Win32-OpenSSH-and-Design-Details.md index ab23f85..19ccd72 100644 --- a/About-Win32-OpenSSH-and-Design-Details.md +++ b/About-Win32-OpenSSH-and-Design-Details.md @@ -24,7 +24,7 @@ POSIX IO calls are a significant part of OpenSSH code. A POSIX IO wrapper will b + operations on a single file descriptor - fd_set, FD_* macros, fcntl, read, write, recv, send, fstat, fdopen, close, dup and dup2 + operations on multiple file descriptors - select + signal semantics on these operations - ex. select (or any blocking IO call) returning EINTR -+ SIGABRT, SIGTERM, SIGCHLD, SIGINT, SIGPIPE and SIGALRM ++ Apart from these, the wrapper also bridges the gap on POSIX signal(). Details below. Design summary of POSIX wrapper + Single threaded (not thread safe based on current needs but can be made so if needed going forward). @@ -39,6 +39,19 @@ Design summary of POSIX wrapper + FD_CLOEXEC is supported, setting this flag denies inheritance of underlying Windows handle. + Uses [APCs](https://msdn.microsoft.com/en-us/library/windows/desktop/ms681951(v=vs.85).aspx) wherever available and minimzing use of [events](https://msdn.microsoft.com/en-us/library/windows/desktop/ms682655(v=vs.85).aspx). This simplifies code and has performance benefits. + Maintains internal buffers to accommodate a fundamental underlying difference between POSIX and Win32 IO async models - IOReady Vs IOComplete (Ex for a Read operation, POSIX APIs signal when IO is ready - data will be subsequently explicitly read, Win32 APIs signal when IO has completed - data is already copied to a user provided buffer. Though the internal buffer and additional copy may seem to be a performance hit, a validation exercise did not show any major impact. It in fact proved beneficial in reducing kernel calls during "read"s (ex. reading a header, would fetch the entire packet in a single call). ++ Maintains Interrupt queue and interrupt handler mapping table. Queue is maintained to temporarily hold interrupts that are otherwise supported in Windows but handled in a different approach typically in a different thread. Ex SIGINT, SIGWINCH. These are processed inside of "wait_for_any" in the main thread. On processing any queued interrupt, this function will return SIGINT. ++ Details on different interrupts handled by OPENSSH code and how they will be handled in Windows +| Signal | Detail | +|:-------|:-------| +|SIGINT |Windows invokes its Ctrl+C handler on a different thread, that handler queues the interrupt in the internal queue and handled by any of the blocking calls (select, etc) | +|SIGWINCH|Like Ctrl+C, a console windows size change event is captured in a native handled, queued and processed in one of the blocking calls | +| SIGILL, SIGTERM, SIGQUIT, WJSIGNAL,SIGTTIN, SIGTTOU | Not generated in Windows, these may be defined by handlers will never be invoked | +| SIGHUP | TBD | +| SIGCHLD | TBD | +|SIGTSTP | TBD | +|SIGPIPE | only accepts SIG_IGN handler (that's all OpenSSH uses) | +|SIGALARM | implemented internally inside the wrapper. handler automatically called when native timer set by CreateWaitableTimer expires | + + Additional details on underlying Win32 calls used | POSIX IO call | Underlying Win32 IO call(s) | Additional details | @@ -56,6 +69,7 @@ Design summary of POSIX wrapper | fstat | TBD | | | dup, dup2 | SetStdHandle | only supported on standard IO file descriptors (used for IO redirection) | | socketpair | CreateNamedPipe | A bi directional named pipe with an internal name is created, CreateFile called to connect from other end. This does not support AF_UNIX ancilliary messages. More details later | +| setitimer | CreateWaitableTimer | A fully functional prototype (for socket, file and pipe IO) of this wrapper is available [here](https://github.com/PowerShell/Win32-OpenSSH/tree/L2-Win32Posix-Prototype/contrib/win32/w32-posix-prototype/win32posix.)