From 3e52a92a71d9a0f46846c515105c562496a09a18 Mon Sep 17 00:00:00 2001
From: Thomas Munro <thomas.munro@enterprisedb.com>
Date: Mon, 22 Jan 2018 15:30:56 +1300
Subject: [PATCH] Update documentation to mention huge pages on other OSes.

Previously the docs implied that only Linux and Windows could use huge pages.
That's not quite true: it's just that we only know how to request them
explicitly on those OSes.  Be more explicit about what huge_pages really does
and mention that some OSes may use huge pages automatically.

Author: Thomas Munro and Catalin Iacob
Reviewed-By: Justin Pryzby, Peter Eisentraut
Discussion: https://postgr.es/m/CAEepm=3qzR-hfjepymohuC4XO5phxoSoipOjm6BEhnJHjNR+jg@mail.gmail.com
---
 doc/src/sgml/config.sgml | 34 ++++++++++++++++++++++++----------
 1 file changed, 24 insertions(+), 10 deletions(-)

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index cc156c6385e..a7a8a765973 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -1363,14 +1363,15 @@ include_dir 'conf.d'
       </term>
       <listitem>
        <para>
-        Enables/disables the use of huge memory pages. Valid values are
-        <literal>try</literal> (the default), <literal>on</literal>,
-        and <literal>off</literal>.
+        Controls whether huge pages are requested for the main shared memory
+        area. Valid values are <literal>try</literal> (the default),
+        <literal>on</literal>, and <literal>off</literal>.
        </para>
 
        <para>
-        At present, this feature is supported only on Linux and Windows. The
-        setting is ignored on other systems when set to <literal>try</literal>.
+        At present, explicitly requesting huge pages is supported only on
+        Linux and Windows. The setting is ignored on other systems when set
+        to <literal>try</literal>.
        </para>
 
        <para>
@@ -1392,11 +1393,24 @@ include_dir 'conf.d'
        </para>
 
        <para>
-        With <varname>huge_pages</varname> set to <literal>try</literal>,
-        the server will try to use huge pages, but fall back to using
-        normal allocation if that fails. With <literal>on</literal>, failure
-        to use huge pages will prevent the server from starting up. With
-        <literal>off</literal>, huge pages will not be used.
+        With <varname>huge_pages</varname> set to <literal>try</literal>, the
+        server will try to request huge pages, but fall back to the default if
+        that fails. With <literal>on</literal>, failure to request huge pages
+        will prevent the server from starting up. With
+        <literal>off</literal>, huge pages will not be requested.
+       </para>
+
+       <para>
+        Note that, besides explicitly requesting huge pages via
+        <varname>huge_pages</varname>, operating systems including Linux,
+        FreeBSD and Illumos can also use huge pages (also known as "super"
+        pages or "large" pages) automatically, without an explicit request from
+        <productname>PostgreSQL</productname>. In Linux this automatic use is
+        called "transparent huge pages" and is not enabled by default in
+        popular distributions as of the time of writing, but since transparent
+        huge pages are known to cause performance degradation with
+        <productname>PostgreSQL</productname> on current Linux versions (unlike
+        explicit use of <varname>huge_pages</varname>), their use is discouraged.
        </para>
       </listitem>
      </varlistentry>
-- 
2.15.1