getting started: add hugepages section

renamed "min_to_use_1g" to "threshold_to_use_1g" since this variable
has been changed in commit 629.

Change-Id: Ie2ca9c71c086d07a0773966cc55dfb61d43edaaa
Signed-off-by: Sona Sarmadi <sona.sarmadi@enea.com>

1 files changed, 122 insertions, 1 deletions

diff --git a/doc/book-enea-nfv-access-getting-started/doc/getting_started_nfv_access.xml b/doc/book-enea-nfv-access-getting-started/doc/getting_started_nfv_access.xml
index 0b3121c..49dc4d4 100644
--- a/doc/book-enea-nfv-access-getting-started/doc/getting_started_nfv_access.xml
+++ b/doc/book-enea-nfv-access-getting-started/doc/getting_started_nfv_access.xml
@@ -419,7 +419,7 @@ sdb            8:0            0     111.8G  0  disk
 
           <para>Modifying any of the Default parameters (e.g Core isolation,
           1G huge page count, etc.) will automatically update the kernel
-          paramters string shown. </para>
+          paramters string shown.</para>
 
           <note>
             <para>Updating the Custom parameters within the kernel string
@@ -570,6 +570,127 @@ run</programlisting>
     </section>
   </section>
 
+  <section id="hugepage_reservation">
+    <title>Hugepage Reservation Service</title>
+
+    <para>NFV Access implements an automatic hugepage allocation service that
+    is triggered at each startup. The service is skipped if hugepages have been
+    allocated in the kernel boot command line.</para>
+
+    <para>There are two strategies outlined for hugepage
+    allocation:</para>
+
+    <itemizedlist>
+      <listitem>
+        <para>If a system has an amount of memory that's lower than 8GB, at least
+        30% of the memory will be reserved to user space applications. 1GB of this
+        memory will be reserved for hugepages 2MB per page size.</para>
+      </listitem>
+
+      <listitem>
+        <para>If a system has an amount of memory that's higher than 8GB, then it
+        will use 1GB hugepages 2MB per page size and leave a predefined amount of 
+        memory for the user space applications.</para>
+      </listitem>
+    </itemizedlist>
+
+    <section id="hugepage_customizing_auto">
+      <title>Customizing Automatic Hugepage Reservation</title>
+
+      <para>Configuration of Hugepage Reservation Service is done in
+      <literal>/etc/enea-nfv-access/hugepages.cfg</literal>.</para>
+
+      <para><emphasis role="bold">Parameters used by the automatic algorithm: </emphasis></para>
+
+      <itemizedlist spacing="compact">
+        <listitem>
+          <para><literal>hugepage_setup</literal>: Enables the automatic configuraiton algorithm.          It has only one value, <literal>auto</literal>. For manual configuration comment or
+          remove the parameter. Use the other parameter descriptions as a template/example.</para>
+        </listitem>
+
+        <listitem>
+          <para><literal>threshold_to_use_1g</literal>: Decides the threshold which instructs the
+          algorithm to use 1GB hugepages. If a system's memory is higher than
+          <literal>threshold_to_use_1g</literal>, then the algorithm will use 1GB
+          hugepages, otherwise it will use 2MB hugepages.</para>
+        </listitem>
+
+        <listitem>
+          <para><literal>percent_os_alloc</literal>: Decides how much memory to try to reserve for
+          userspace applications. The algorithm will try to reserve at least
+          <literal>percent_os_alloc</literal> of the total system memory to
+          user space applications.</para>
+        </listitem>
+
+        <listitem>
+          <para><literal>maximum_os_alloc_mb</literal>: Maximum amount of memory to allocate for
+          userspace applications. If <literal>percent_os_alloc</literal> of
+          the total system memory exceeds
+          <literal>maximum_os_alloc_mb</literal> then the maximum allocated
+          memory for userspace applications is
+          <literal>maximum_os_alloc_mb</literal>.</para>
+        </listitem>
+      </itemizedlist>
+      <para><emphasis role="bold">Example of automatic Hugepage Configuration:</emphasis></para>
+
+      <programlisting> hugepage_setup = auto
+ threshold_to_use_1g = 8192
+ percent_os_alloc = 50
+ maximum_os_alloc_mb = 1024</programlisting>
+
+      <para>The following possible allocations could result
+            (based on total system memory available):</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>2GB of memory: approximately 616MB allocated for userspace
+          applications and 1432MB allocated as 2MB hugepages.</para>
+        </listitem>
+
+        <listitem>
+          <para>4GB of memory: 1024MB allocated for userspace applications and
+          7168MB as hugepages.</para>
+        </listitem>
+
+        <listitem>
+          <para>16GB of memory: 1GB allocated for userspace applications and
+          15GB as 1GB hugepages.</para>
+        </listitem>
+      </itemizedlist>
+    </section>
+
+    <section id="hugepage_customizing_man">
+      <title>Customizing Manual Hugepage Reservation</title>
+
+      <para>The automatic algorithm can be disabled and hugepages configured
+      manually. To do this, comment the line which defines
+      <literal>hugepage_setup</literal> as <literal>auto</literal> and
+      configure memory for each CPU socket in the following manner:</para>
+
+      <programlisting>&lt;NUMA node&gt;.&lt;hugepage size&gt; = &lt;number of pages&gt; </programlisting>
+
+      <para>Where <literal>&lt;NUMA node&gt;</literal> refers to a node which
+      is part of the system's NUMA topology, <literal>&lt;hugepage
+      size&gt;</literal> decides what type of hugepages should be set and
+      <literal>&lt;number of hugepages&gt;</literal> is how many hugepages of
+      <literal>&lt;hugepage size&gt;</literal> should be allocated.</para>
+
+      <para>To list the available system nodes, run:</para>
+
+      <programlisting>ls -d /sys/devices/system/node/node* </programlisting>
+
+      <para>To list available hugepage sizes, per node, run:</para>
+
+      <programlisting>ls -d /sys/devices/system/node/node*/hugepages/hugepages-*</programlisting>
+
+      <para>Example of Manual Hugepage Configuration,
+      to configure the sytem to allocate e.g. 3 1GB hugepages and 512 2MB hugepages on node:</para>
+
+      <programlisting>node0.2048kB = 512
+                      node0.1048576kB = 3 </programlisting>
+    </section>
+  </section>
+
   <section condition="hidden" id="release-content">
     <title>NFV Access Release content</title>