LUDOC-11 misc: cleanup formatting of TBF examples

Minor cleanups of examples for NRS TBF and other misc cleanups.

Signed-off-by: Andreas Dilger <andreas.dilger@intel.com>
Change-Id: I4717ac50e68e0cc5635f4702c818314c8f9532c5
Reviewed-on: https://review.whamcloud.com/24804
Tested-by: Jenkins
Reviewed-by: Joseph Gmitter <joseph.gmitter@intel.com>

diff --git a/LustreTuning.xml b/LustreTuning.xml
index e98574a..7caf0e6 100644 (file)
--- a/LustreTuning.xml
+++ b/LustreTuning.xml
@@ -1138,7 +1138,7 @@ ost.OSS.ost_io.nrs_orr_supported=reg_supported:reads_and_writes
         </listitem>
       </itemizedlist>
     </section>
         </listitem>
       </itemizedlist>
     </section>

-    <section condition='l26'>
+    <section xml:id="dbdoclet.tbftuning" condition='l26'>

       <title>
       <indexterm>
         <primary>tuning</primary>
       <title>
       <indexterm>
         <primary>tuning</primary>


@@ -1190,9 +1190,7 @@ ost.OSS.ost_io.nrs_orr_supported=reg_supported:reads_and_writes
           follows:</para>
           <screen>
 $ lctl set_param x.x.x.nrs_tbf_rule=
           follows:</para>
           <screen>
 $ lctl set_param x.x.x.nrs_tbf_rule=

-                  "[reg|hp] start 
-<replaceable>rule_name</replaceable> 
-<replaceable>arguments</replaceable>..."
+          "[reg|hp] start <replaceable>rule_name</replaceable> <replaceable>arguments</replaceable>..."

 </screen>
           <para>The '
           <replaceable>rule_name</replaceable>' argument is a string which
 </screen>
           <para>The '
           <replaceable>rule_name</replaceable>' argument is a string which


@@ -1202,10 +1200,7 @@ $ lctl set_param x.x.x.nrs_tbf_rule=
           as follows:</para>
           <screen>
 $ lctl set_param x.x.x.nrs_tbf_rule=
           as follows:</para>
           <screen>
 $ lctl set_param x.x.x.nrs_tbf_rule=

-                  "[reg|hp] start 
-<replaceable>rule_name</replaceable> {
-<replaceable>nidlist</replaceable>} 
-<replaceable>rate</replaceable>"
+          "[reg|hp] start <replaceable>rule_name</replaceable> {<replaceable>nidlist</replaceable>} <replaceable>rate</replaceable>"

 </screen>
           <para>The format of '
           <replaceable>nidlist</replaceable>' argument is the same as the
 </screen>
           <para>The format of '
           <replaceable>nidlist</replaceable>' argument is the same as the


@@ -1217,64 +1212,59 @@ $ lctl set_param x.x.x.nrs_tbf_rule=
           critical too.</para>
           <screen>
 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule=
           critical too.</para>
           <screen>
 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule=

-                  "start other_clients {192.168.*.*@tcp} 50"
+          "start other_clients {192.168.*.*@tcp} 50"

 </screen>
           <screen>
 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule=
 </screen>
           <screen>
 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule=

-                  "start loginnode {192.168.1.1@tcp} 100"
+          "start loginnode {192.168.1.1@tcp} 100"

 </screen>
           <para>General rule can be replaced by two rules (reg and hp) as
           follows:</para>
           <screen>
 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule=
 </screen>
           <para>General rule can be replaced by two rules (reg and hp) as
           follows:</para>
           <screen>
 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule=

-                  "reg start loginnode {192.168.1.1@tcp} 100"
+          "reg start loginnode {192.168.1.1@tcp} 100"

 </screen>
           <screen>
 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule=
 </screen>
           <screen>
 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule=

-                  "hp start loginnode {192.168.1.1@tcp} 100"
+          "hp start loginnode {192.168.1.1@tcp} 100"

 </screen>
           <screen>
 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule=
 </screen>
           <screen>
 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule=

-                  "start computes {192.168.1.[2-128]@tcp} 500"
+          "start computes {192.168.1.[2-128]@tcp} 500"

 </screen>
           <para>The above rules will put an upper limit for servers to process
           at most 5x as many RPCs from compute nodes as login nodes.</para>
 </screen>
           <para>The above rules will put an upper limit for servers to process
           at most 5x as many RPCs from compute nodes as login nodes.</para>

-          <para>For the JobID (please see 
+          <para>For the JobID (please see

           <xref xmlns:xlink="http://www.w3.org/1999/xlink"
           <xref xmlns:xlink="http://www.w3.org/1999/xlink"

-          linkend="dbdoclet.jobstats" />for more details) based TBF policy, its
-          format is as follows:</para>
+                linkend="dbdoclet.jobstats" /> for more details) based TBF
+          policy, its format is as follows:</para>

           <screen>
 $ lctl set_param x.x.x.nrs_tbf_rule=
           <screen>
 $ lctl set_param x.x.x.nrs_tbf_rule=

-                  "[reg|hp] start 
-<replaceable>name</replaceable> {
-<replaceable>jobid_list</replaceable>} 
-<replaceable>rate</replaceable>"
+          "[reg|hp] start <replaceable>name</replaceable> {<replaceable>jobid_list</replaceable>} <replaceable>rate</replaceable>"

 </screen>
           <para>Following commands are valid:</para>
           <screen>
 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule=
 </screen>
           <para>Following commands are valid:</para>
           <screen>
 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule=

-                  "start user1 {iozone.500 dd.500} 100"
+          "start user1 {iozone.500 dd.500} 100"

 </screen>
           <screen>
 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule=
 </screen>
           <screen>
 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule=

-                  "start iozone_user1 {iozone.500} 100"
+          "start iozone_user1 {iozone.500} 100"

 </screen>
           <para>Same as nid, could use reg and hp rules separately:</para>
           <screen>
 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule=
 </screen>
           <para>Same as nid, could use reg and hp rules separately:</para>
           <screen>
 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule=

-                  "hp start iozone_user1 {iozone.500} 100"
+          "hp start iozone_user1 {iozone.500} 100"

 </screen>
           <screen>
 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule=
 </screen>
           <screen>
 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule=

-                  "reg start iozone_user1 {iozone.500} 100"
+          "reg start iozone_user1 {iozone.500} 100"

 </screen>
           <para>The format of the rule change command of TBF policy is as
           follows:</para>
           <screen>
 $ lctl set_param x.x.x.nrs_tbf_rule=
 </screen>
           <para>The format of the rule change command of TBF policy is as
           follows:</para>
           <screen>
 $ lctl set_param x.x.x.nrs_tbf_rule=

-                  "[reg|hp] change 
-<replaceable>rule_name</replaceable> 
-<replaceable>rate</replaceable>"
+          "[reg|hp] change <replaceable>rule_name</replaceable> <replaceable>rate</replaceable>"

 </screen>
           <para>Following commands are valid:</para>
           <screen>
 </screen>
           <para>Following commands are valid:</para>
           <screen>


@@ -1313,8 +1303,8 @@ $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule="hp stop loginnode"
       <secondary>lockless I/O</secondary>
     </indexterm>Lockless I/O Tunables</title>
     <para>The lockless I/O tunable feature allows servers to ask clients to do
       <secondary>lockless I/O</secondary>
     </indexterm>Lockless I/O Tunables</title>
     <para>The lockless I/O tunable feature allows servers to ask clients to do

-    lockless I/O (liblustre-style where the server does the locking) on
-    contended files.</para>
+    lockless I/O (the server does the locking on behalf of clients) for
+    contended files to avoid lock ping-pong.</para>

     <para>The lockless I/O patch introduces these tunables:</para>
     <itemizedlist>
       <listitem>
     <para>The lockless I/O patch introduces these tunables:</para>
     <itemizedlist>
       <listitem>


@@ -1322,7 +1312,7 @@ $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule="hp stop loginnode"
           <emphasis role="bold">OST-side:</emphasis>
         </para>
         <screen>
           <emphasis role="bold">OST-side:</emphasis>
         </para>
         <screen>

-/proc/fs/lustre/ldlm/namespaces/filter-lustre-*
+ldlm.namespaces.filter-<replaceable>fsname</replaceable>-*.

 </screen>
         <para>
         <literal>contended_locks</literal>- If the number of lock conflicts in
 </screen>
         <para>
         <literal>contended_locks</literal>- If the number of lock conflicts in


@@ -1333,9 +1323,9 @@ $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule="hp stop loginnode"
         contended state as set in the parameter.</para>
         <para>
         <literal>max_nolock_bytes</literal>- Server-side locking set only for
         contended state as set in the parameter.</para>
         <para>
         <literal>max_nolock_bytes</literal>- Server-side locking set only for

-        requests less than the blocks set in the 
-        <literal>max_nolock_bytes</literal> parameter. If this tunable is set to
-        zero (0), it disables server-side locking for read/write
+        requests less than the blocks set in the
+        <literal>max_nolock_bytes</literal> parameter. If this tunable is
+        set to zero (0), it disables server-side locking for read/write

         requests.</para>
       </listitem>
       <listitem>
         requests.</para>
       </listitem>
       <listitem>


@@ -1548,23 +1538,25 @@ $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule="hp stop loginnode"
     <indexterm>
       <primary>tuning</primary>
       <secondary>for small files</secondary>
     <indexterm>
       <primary>tuning</primary>
       <secondary>for small files</secondary>

-    </indexterm>Improving Lustre File System Performance When Working with
-    Small Files</title>
+    </indexterm>Improving Lustre I/O Performance for Small Files</title>

     <para>An environment where an application writes small file chunks from
     <para>An environment where an application writes small file chunks from

-    many clients to a single file will result in bad I/O performance. To
+    many clients to a single file can result in poor I/O performance. To

     improve the performance of the Lustre file system with small files:</para>
     <itemizedlist>
       <listitem>
         <para>Have the application aggregate writes some amount before
         submitting them to the Lustre file system. By default, the Lustre
         software enforces POSIX coherency semantics, so it results in lock
     improve the performance of the Lustre file system with small files:</para>
     <itemizedlist>
       <listitem>
         <para>Have the application aggregate writes some amount before
         submitting them to the Lustre file system. By default, the Lustre
         software enforces POSIX coherency semantics, so it results in lock

-        ping-pong between client nodes if they are all writing to the same file
-        at one time.</para>
+        ping-pong between client nodes if they are all writing to the same
+        file at one time.</para>
+        <para>Using MPI-IO Collective Write functionality in
+        the Lustre ADIO driver is one way to achieve this in a straight
+        forward manner if the application is already using MPI-IO.</para>

       </listitem>
       <listitem>
       </listitem>
       <listitem>

-        <para>Have the application do 4kB 
-        <literal>O_DIRECT</literal> sized I/O to the file and disable locking on
-        the output file. This avoids partial-page IO submissions and, by
+        <para>Have the application do 4kB
+        <literal>O_DIRECT</literal> sized I/O to the file and disable locking
+        on the output file. This avoids partial-page IO submissions and, by

         disabling locking, you avoid contention between clients.</para>
       </listitem>
       <listitem>
         disabling locking, you avoid contention between clients.</para>
       </listitem>
       <listitem>