WIP: Migrate Wiki content over to src/docs

docs/cygwin_dll_remapping_failure.md

Index: docs/cygwin_dll_remapping_failure.md
diff --git a/docs/cygwin_dll_remapping_failure.md b/docs/cygwin_dll_remapping_failure.md
new file mode 100644
index 0000000000000000000000000000000000000000..3b56273dd8405d3ba442be07e627009ca1b684f6
--- /dev/null
+++ b/docs/cygwin_dll_remapping_failure.md
@@ -0,0 +1,55 @@
+Handling repeated failures of rebaseall to allow cygwin remaps
+
+# Introduction
+
+Sometimes DLLs over which cygwin has no control get mapped into cygwin
+processes at locations that cygwin has chosen for its libraries.
+This has been seen primarily with anti-virus DLLs.  When this occurs,
+cygwin must be instructed during the rebase to avoid the area of
+memory where that DLL is mapped.
+
+# Background
+
+Some background for this is available on http://www.dont-panic.cc/capi/2007/10/29/git-svn-fails-with-fatal-error-unable-to-remap/
+
+Because of unix fork semantics (presumably), cygwin libraries must be
+mapped in the same location in both parent and child of a fork.  All
+cygwin libraries have hints in them as to where they should be mapped
+in a processes address space; if those hints are followed, each
+library will be mapped in the same location in both address spaces.
+However, Windows is perfectly happy mapping a DLL anywhere in the
+address space; the hint is not considered controlling.  The remapping
+error occurs when a cygwin process starts and one of its libraries
+cannot be mapped to the location specified by its hint.
+
+/usr/bin/rebaseall changes the DLL hints for all of the cygwin
+libraries so that there are no inter-library conflicts; it does this
+by choosing a contiguous but not overlapping library layout starting
+at a base address and working down.  This process makes sure there are
+no intra-cygwin conflicts, but cannot deal with conflicts with
+external DLLs that are in cygwin process address spaces
+(e.g. anti-virus DLLs).
+
+To handle this case, you need to figure out what the problematic
+non-cygwin library is, where it is in the address space, and do the
+rebase all so that no cygwin hints map libraries to that location.
+
+# Details
+
+<ul>
+<li>Download the ListDLLs executable from sysinternals<br>
+(<a href='http://technet.microsoft.com/en-us/sysinternals/bb896656.aspx'>http://technet.microsoft.com/en-us/sysinternals/bb896656.aspx</a>)</li>
+<li>Run it as administrator while some cygwin commands are running.</li>
+<li>Scan the output for the cygwin process (identifiable by the command) and for DLLs in that process that do not look like cygwin DLLs (like an AV).  Note the location of those libraries (there will usually only be the one).  Pick an address space location lower than its starting address.</li>
+<li>Quit all cygwin processes.</li>
+<li>Run a windows command shell as administrator</li>
+<li>cd in \cygwin\bin</li>
+<li>Run "ash /usr/bin/rebaseall -b <base address>" (This command can also take a "-v" flag if you want to see the DLL layout.)</li>
+</ul>
+
+
+That should fix the problem.
+
+# Failed rebaseall
+
+If you pick a base address that is too low, you may end up with a broken cygwin install. You can reinstall it by running cygwin's setup.exe again, and on the package selection page, clicking the "All" entry to Reinstall. You may have to do this twice, as you may get errors on the first reinstall pass.