* new-features.sgml (ov-new1.7.10): Document large address awareness

	of heap and new way to set the default heap size per executable.
	* setup2.sgml (setup-maxmem): Revamp to explain new method of
	allocating more heap on a per-executable basis.  Drop outdated stuff.
	Keep shortened description of heap_chunk_in_mb as note.

3 files changed, 61 insertions, 44 deletions

diff --git a/winsup/doc/ChangeLog b/winsup/doc/ChangeLog
index 35eaa544e..643a26845 100644
--- a/winsup/doc/ChangeLog
+++ b/winsup/doc/ChangeLog
@@ -1,3 +1,11 @@
+2011-08-12  Corinna Vinschen  <corinna@vinschen.de>
+
+	* new-features.sgml (ov-new1.7.10): Document large address awareness
+	of heap and new way to set the default heap size per executable.
+	* setup2.sgml (setup-maxmem): Revamp to explain new method of
+	allocating more heap on a per-executable basis.  Drop outdated stuff.
+	Keep shortened description of heap_chunk_in_mb as note.
+
 2011-08-04  Corinna Vinschen  <corinna@vinschen.de>
 
 	* faq-using.xml (faq.using.bloda): Add NVIDIA.  Change wording slightly.
diff --git a/winsup/doc/new-features.sgml b/winsup/doc/new-features.sgml
index aff63d928..f13bf71eb 100644
--- a/winsup/doc/new-features.sgml
+++ b/winsup/doc/new-features.sgml
@@ -14,6 +14,20 @@ The CYGWIN environment variable options "envcache", "strip_title", "title",
 </para></listitem>
 
 <listitem><para>
+If the executable (and the system) is large address aware, the application heap
+will be placed in the large memory area.  The <command>peflags</command> tool
+from the <literal>rebase</literal> package can be used to set the large
+address awareness flag in the executable file header.
+</para></listitem>
+
+<listitem><para>
+The registry setting "heap_chunk_in_mb" has been removed, in favor of a new
+per-executable setting in the executable file header which can be set using the
+<command>peflags</command> tool.  See <xref linkend="setup-maxmem"></xref>
+for more information.
+</para></listitem>
+
+<listitem><para>
 The CYGWIN=tty mode using pipes to communicate with the console in a pseudo
 tty-like mode has been removed.  Either just use the normal Windows console
 as is, or use a terminal application like <command>mintty</command>.
diff --git a/winsup/doc/setup2.sgml b/winsup/doc/setup2.sgml
index 6a5a5e757..1ffe8f8f8 100644
--- a/winsup/doc/setup2.sgml
+++ b/winsup/doc/setup2.sgml
@@ -138,65 +138,60 @@ environment.  In these cases, you have to call the aforementioned
 Cygwin's heap is extensible.  However, it does start out at a fixed size
 and attempts to extend it may run into memory which has been previously
 allocated by Windows.  In some cases, this problem can be solved by
-adding 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>
+changing a field in the file header which is utilized by Cygwin since
+version 1.7.10 to keep the initial size of the application heap.  If the
+field contains 0, which is the default, the application heap defaults to
+a size of 384 Megabyte.  If the field is set to any other value between 4 and
+2048, Cygwin tries to reserve as much Megabytes for the application heap.
+The field used for this is the "LoaderFlags" field in the NT-specific
+PE header structure (<literal>(IMAGE_NT_HEADER)->OptionalHeader.LoaderFlags</literal>).</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"></xref> or use 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:
+This value can be changed for any executable by using a more recent version
+of the <command>peflags</command> tool from the <literal>rebase</literal>
+Cygwin package.  Example:
 
 <screen>
-regtool -i set /HKLM/Software/Cygwin/heap_chunk_in_mb 1024
-regtool -v list /HKLM/Software/Cygwin
+$ peflags --cygwin-heap foo.exe
+foo.exe: initial Cygwin heap size: 0 (0x0) MB
+$ peflags --cygwin-heap=500 foo.exe
+foo.exe: initial Cygwin heap size: 500 (0x1f4) MB
 </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.  
+Heap memory can be allocated up to the size of the biggest available free
+block in the processes virtual memory (VM).  By default, the VM per process
+is 2 GB for 32 processes.  To get more VM for a process, the executable
+must have the "large address aware" flag set in the file header.  You can
+use the aforementioned <command>peflags</command> tool to set this flag.
+On 64 bit systems this results in a 4 GB VM for a process started from that
+executable.  On 32 bit systems you also have to prepare the system to allow
+up to 3 GB per process.  See the Microsoft article
+<ulink url="http://msdn.microsoft.com/en-us/library/bb613473%28VS.85%29.aspx">4-Gigabyte Tuning</ulink>
+for more information.
 </para>
 
+<note>
 <para>
-Here is a small program written by DJ Delorie that tests the 
-memory allocation limit on your system:
+Older Cygwin releases only supported a global registry setting to
+change the initial heap size for all Cygwin processes.  This setting is
+not used anymore.  However, if you're running an older Cygwin release
+than 1.7.10, you can add the <literal>DWORD</literal> value
+<literal>heap_chunk_in_mb</literal> and set it to the desired memory limit
+in decimal MB.  You have to stop all Cygwin processes for this setting to
+have any effect.  It is preferred to do this in Cygwin using the
+<command>regtool</command> program included in the Cygwin package.
+(see <xref linkend="regtool"></xref>) This example sets the memory limit
+to 1024 MB for all Cygwin processes (use HKCU instead of HKLM if you
+want to set this only for the current user):
 
 <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;
-}
+$ regtool -i set /HKLM/Software/Cygwin/heap_chunk_in_mb 1024
+$ regtool -v list /HKLM/Software/Cygwin
 </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>
+</note>
 
 </sect1>