Modernized user guide, API reference, and FAQ generation. Overall

effect is to move away from DocBook SGML and DJ Delorie's doctool and
toward pure DocBook XSL.  (There remains just one use of doctool, and
we have plans for replacing it, too.)  See ChangeLog for details.

1 files changed, 66 insertions, 0 deletions

diff --git a/winsup/doc/setup-maxmem.xml b/winsup/doc/setup-maxmem.xml
new file mode 100644
index 000000000..1f5ee31a6
--- /dev/null
+++ b/winsup/doc/setup-maxmem.xml
@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding='UTF-8'?>
+<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook V4.5//EN"
+		"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
+
+<sect1 id="setup-maxmem"><title>Changing Cygwin's Maximum Memory</title>
+
+<para>
+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
+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>
+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>
+$ 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>
+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>
+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>
+$ regtool -i set /HKLM/Software/Cygwin/heap_chunk_in_mb 1024
+$ regtool -v list /HKLM/Software/Cygwin
+</screen>
+</para>
+</note>
+
+</sect1>