* setup-net.sgml: Add "setup-maxmem" section

2 files changed, 69 insertions, 0 deletions

diff --git a/winsup/doc/setup-net.sgml b/winsup/doc/setup-net.sgml
index cc40f312b..547439249 100644
--- a/winsup/doc/setup-net.sgml
+++ b/winsup/doc/setup-net.sgml
@@ -10,6 +10,7 @@ Follow the instructions on each screen to install Cygwin.</para>
 </sect1>
 
 DOCTOOL-INSERT-setup-env
+DOCTOOL-INSERT-setup-maxmem
 DOCTOOL-INSERT-ntsec
 DOCTOOL-INSERT-setup-files
 </chapter>
diff --git a/winsup/doc/setup2.sgml b/winsup/doc/setup2.sgml
index 4b2ecf6ef..592a25dc2 100644
--- a/winsup/doc/setup2.sgml
+++ b/winsup/doc/setup2.sgml
@@ -55,6 +55,74 @@ first starts.  Most Cygwin applications do not make use of the
 
 </sect1>
 
+<sect1 id="setup-maxmem"><title>Changing Cygwin's Maximum Memory</title>
+
+<para>
+By default no Cygwin program can allocate more than 384 MB of memory 
+(program+data).  You should not need to change this default in most 
+circumstances.  However, if you need to use more real or virtual memory in 
+your machine you may add an entry in the either the 
+<literal>HKEY_LOCAL_MACHINE</literal> (to change the limit for all users) or 
+<literal>HKEY_CURRENT_USER</literal> (for just the current user) section of 
+the registry. 
+</para>
+
+<para>
+Add the <literal>DWORD</literal> value <literal>heap_chunk_in_mb</literal> 
+and set it to the desired memory limit in decimal MB. It is preferred to do 
+this in Cygwin using the <command>regtool</command> program included in the 
+Cygwin package.
+(For more information about <command>regtool</command> or the other Cygwin 
+utilities, see <Xref Linkend="using-utils"> or use each the
+<literal>--help</literal> option of each util.)  You should always be careful 
+when using <command>regtool</command> since damaging your system registry can 
+result in an unusable system.  This example sets memory limit to 1024 MB:
+
+<screen>
+regtool -i set /HKLM/Software/Cygnus\ Solutions/Cygwin/heap_chunk_in_mb 1024
+regtool -v list /HKLM/Software/Cygnus\ Solutions/Cygwin
+</screen>
+</para>
+
+<para>
+Exit all running Cygwin processes and restart them. Memory can be allocated up 
+to the size of the system swap space minus any the size of any running 
+processes. The system swap should be at least as large as the physically 
+installed RAM and can be modified under the System category of the 
+Control Panel.  
+</para>
+
+<para>
+Here is a small program written by DJ Delorie that tests the 
+memory allocation limit on your system:
+
+<screen>
+main()
+{
+  unsigned int bit=0x40000000, sum=0;
+  char *x;
+  
+  while (bit > 4096) 
+  {
+    x = malloc(bit);
+    if (x)
+    sum += bit;
+    bit >>= 1;
+  }
+  printf("%08x bytes (%.1fMb)\n", sum, sum/1024.0/1024.0);
+  return 0;
+}
+</screen>
+
+You can compile this program using:
+<screen>
+gcc max_memory.c -o max_memory.exe
+</screen>
+
+Run the program and it will output the maximum amount of allocatable memory.
+</para>
+</sect1>
+
 <sect1 id="setup-files"><title>Customizing bash</title>
 
 <para>