LUDOC-327 ladvise: Add ladvise documentation.

Add the llapi_ladvise and lfs ladvise documentation to
the manual.  The material was extracted from the
manual patches that were landed for the feature.

Signed-off-by: Joseph Gmitter <joseph.gmitter@intel.com>
Change-Id: I3f0775dd2ceeac3e1a20c28da0c75cfff53e3091
Reviewed-on: https://review.whamcloud.com/23576
Tested-by: Jenkins
Reviewed-by: Andreas Dilger <andreas.dilger@intel.com>
Reviewed-by: James Nunez <james.a.nunez@intel.com>

diff --git a/LustreTuning.xml b/LustreTuning.xml
index 2e3a496..a73f870 100644 (file)
--- a/LustreTuning.xml
+++ b/LustreTuning.xml
@@ -1368,6 +1368,131 @@ $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule="hp stop loginnode"
       </listitem>
     </itemizedlist>
   </section>
+  <section condition="l29">
+      <title>
+        <indexterm>
+          <primary>tuning</primary>
+          <secondary>with lfs ladvise</secondary>
+        </indexterm>
+        Server-Side Advice and Hinting
+      </title>
+      <section><title>Overview</title>
+      <para>Use the <literal>lfs ladvise</literal> command give file access
+      advices or hints to servers.</para>
+      <screen>lfs ladvise [--advice|-a ADVICE ] [--background|-b]
+[--start|-s START[kMGT]]
+{[--end|-e END[kMGT]] | [--length|-l LENGTH[kMGT]]}
+<emphasis>file</emphasis> ...
+      </screen>
+      <para>
+        <informaltable frame="all">
+          <tgroup cols="2">
+          <colspec colname="c1" colwidth="50*"/>
+          <colspec colname="c2" colwidth="50*"/>
+          <thead>
+            <row>
+              <entry>
+                <para><emphasis role="bold">Option</emphasis></para>
+              </entry>
+              <entry>
+                <para><emphasis role="bold">Description</emphasis></para>
+              </entry>
+            </row>
+          </thead>
+          <tbody>
+            <row>
+              <entry>
+                <para><literal>-a</literal>, <literal>--advice=</literal>
+                <literal>ADVICE</literal></para>
+              </entry>
+              <entry>
+                <para>Give advice or hint of type <literal>ADVICE</literal>.
+                Advice types are:</para>
+                <para><literal>willread</literal> to prefetch data into server
+                cache</para>
+                <para><literal>dontneed</literal> to cleanup data cache on
+                server</para>
+              </entry>
+            </row>
+            <row>
+              <entry>
+                <para><literal>-b</literal>, <literal>--background</literal>
+                </para>
+              </entry>
+              <entry>
+                <para>Enable the advices to be sent and handled asynchronously.
+                </para>
+              </entry>
+            </row>
+            <row>
+              <entry>
+                <para><literal>-s</literal>, <literal>--start=</literal>
+                        <literal>START_OFFSET</literal></para>
+              </entry>
+              <entry>
+                <para>File range starts from <literal>START_OFFSET</literal>
+                </para>
+                </entry>
+            </row>
+            <row>
+                <entry>
+                    <para><literal>-e</literal>, <literal>--end=</literal>
+                        <literal>END_OFFSET</literal></para>
+                </entry>
+                <entry>
+                    <para>File range ends at (not including)
+                    <literal>END_OFFSET</literal>.  This option may not be
+                    specified at the same time as the <literal>-l</literal>
+                    option.</para>
+                </entry>
+            </row>
+            <row>
+                <entry>
+                    <para><literal>-l</literal>, <literal>--length=</literal>
+                        <literal>LENGTH</literal></para>
+                </entry>
+                <entry>
+                  <para>File range has length of <literal>LENGTH</literal>.
+                  This option may not be specified at the same time as the
+                  <literal>-e</literal> option.</para>
+                </entry>
+            </row>
+          </tbody>
+          </tgroup>
+        </informaltable>
+      </para>
+      <para>Typically, <literal>lfs ladvise</literal> forwards the advice to
+      Lustre servers without guaranteeing when and what servers will react to
+      the advice. Actions may or may not triggered when the advices are
+      recieved, depending on the type of the advice, as well as the real-time
+      decision of the affected server-side components.</para>
+      <para>A typical usage of ladvise is to enable applications and users with
+      external knowledge to intervene in server-side cache management. For
+      example, if a bunch of different clients are doing small random reads of a
+      file, prefetching pages into OSS cache with big linear reads before the
+      random IO is a net benefit. Fetching that data into each client cache with
+      fadvise() may not be, due to much more data being sent to the client.
+      </para>
+      <para>The main difference between the Linux <literal>fadvise()</literal>
+      system call and <literal>lfs ladvise</literal> is that
+      <literal>fadvise()</literal> is only a client side mechanism that does
+      not pass the advice to the filesystem, while <literal>ladvise</literal>
+      can send advices or hints to the Lustre server side.</para>
+      </section>
+      <section><title>Examples</title>
+        <para>The following example gives the OST(s) holding the first 1GB of
+        <literal>/mnt/lustre/file1</literal>a hint that the first 1GB of the
+        file will be read soon.</para>
+        <screen>client1$ lfs ladvise -a willread -s 0 -e 1048576000 /mnt/lustre/file1
+        </screen>
+        <para>The following example gives the OST(s) holding the first 1GB of
+        <literal>/mnt/lustre/file1</literal> a hint that the first 1GB of file
+        will not be read in the near future, thus the OST(s) could clear the
+        cache of the file in the memory.</para>
+        <screen>client1$ lfs ladvise -a dontneed -s 0 -e 1048576000 /mnt/lustre/file1
+        </screen>
+      </section>
+  </section>
   <section xml:id="dbdoclet.50438272_80545">
     <title>
     <indexterm>

diff --git a/SettingLustreProperties.xml b/SettingLustreProperties.xml
index 930a517..ce5ba82 100644 (file)
--- a/SettingLustreProperties.xml
+++ b/SettingLustreProperties.xml
@@ -829,6 +829,200 @@ int llapi_path2fid(const char *path, unsigned long long *seq, unsigned long *oid
       <para>non-zero value On failure</para>
     </section>
   </section>
+  <section condition="l29">
+      <title>
+          <literal>llapi_ladvise</literal>
+      </title>
+      <para>Use <literal>llapi_ladvise</literal> to give IO advice/hints on a
+      Lustre file to the server.</para>
+      <section remap="h5">
+          <title>Synopsis</title>
+          <screen>
+#include &lt;lustre/lustreapi.h&gt;
+int llapi_ladvise(int fd, unsigned long long flags,
+                  int num_advise, struct llapi_lu_ladvise *ladvise);
+                                
+struct llapi_lu_ladvise {
+  __u16 lla_advice;       /* advice type */
+  __u16 lla_value1;       /* values for different advice types */
+  __u32 lla_value2;
+  __u64 lla_start;        /* first byte of extent for advice */
+  __u64 lla_end;          /* last byte of extent for advice */
+  __u32 lla_value3;
+  __u32 lla_value4;
+};
+          </screen>
+      </section>
+      <section remap="h5">
+          <title>Description</title>
+          <para>The <literal>llapi_ladvise</literal> function passes an array of
+          <emphasis>num_advise</emphasis> I/O hints (up to a maximum of
+          <emphasis>LAH_COUNT_MAX</emphasis> items) in ladvise for the file
+          descriptor <emphasis>fd</emphasis> from an application to one or more
+          Lustre servers.  Optionally, <emphasis>flags</emphasis> can modify how
+          the advice will be processed via bitwise-or'd values:</para>
+          <itemizedlist><listitem>
+          <para><literal>LF_ASYNC</literal>:  Clients return to userspace
+          immediately after submitting ladvise RPCs, leaving server threads to
+          handle the advices asynchronously.</para>
+          </listitem></itemizedlist>
+          <para>Each of the <emphasis>ladvise</emphasis> elements is an
+          <emphasis>llapi_lu_ladvise</emphasis> structure, which contains the
+          following fields:
+          <informaltable frame="all">
+            <tgroup cols="2">
+              <colspec colname="c1" colwidth="50*"/>
+              <colspec colname="c2" colwidth="50*"/>
+              <thead>
+                <row>
+                  <entry>
+                    <para><emphasis role="bold">Field</emphasis></para>
+                  </entry>
+                  <entry>
+                    <para><emphasis role="bold">Description</emphasis></para>
+                  </entry>
+                </row>
+              </thead>
+              <tbody>
+              <row>
+              <entry>
+                <para> <literal>lla_ladvice</literal></para>
+              </entry>
+              <entry>
+                <para>Specifies the advice for the given file range, currently
+                one of:</para>
+                <para><literal>LU_LADVISE_WILLREAD</literal>:  Prefetch data
+                into server cache using optimum I/O size for the server.</para>
+                <para><literal>LU_LADVISE_DONTNEED</literal>:  Clean cached data
+                for the specified file range(s) on the server.</para>
+              </entry>
+              </row>
+              <row>
+                <entry>
+                  <para> <literal>lla_start</literal></para>
+                </entry>
+                <entry>
+                  <para>The offset in bytes for the start of this advice.</para>
+                </entry>
+              </row>
+              <row>
+                <entry>
+                  <para> <literal>lla_end</literal></para>
+                </entry>
+                <entry>
+                  <para>The offset in bytes (non-inclusive) for the end of this
+                  advice.</para>
+                </entry>
+              </row>
+              <row>
+                <entry>
+                  <para> <literal>lla_value1</literal></para>
+                  <para> <literal>lla_value2</literal></para>
+                  <para> <literal>lla_value3</literal></para>
+                  <para> <literal>lla_value4</literal></para>
+                </entry>
+                <entry>
+                    <para>Additional arguments for future advice types and
+                    should be set to zero if not explicitly required for a given
+                    advice type.</para>
+                </entry>
+              </row>
+              </tbody>
+              </tgroup>
+          </informaltable>
+          </para>
+          <para><literal>llapi_ladvise()</literal> forwards the advice to Lustre
+          servers without guaranteeing how and when servers will react to the
+          advice. Actions may or may not be triggered when the advices are
+          received, depending on the type of the advice as well as the real-time
+          decision of the affected server-side components.
+          </para>
+          <para> A typical usage of <literal>llapi_ladvise()</literal> is to
+          enable applications and users (via <literal>lfs ladvise</literal>)
+          with external knowledge about application I/O patterns to intervene in
+          server-side I/O handling. For example, if a group of different clients
+          are doing small random reads of a file, prefetching pages into OSS
+          cache with big linear reads before the random IO is an overall net
+          benefit.  Fetching that data into each client cache with
+          <emphasis>fadvise()</emphasis> may not be beneficial, due to much more
+          data being sent to the clients.
+          </para>
+          <para>While conceptually similar to the
+          <emphasis>posix_fadvise</emphasis> and Linux
+          <emphasis>fadvise</emphasis> system calls, the main difference of
+          <literal>llapi_ladvise()</literal> is that
+          <emphasis>fadvise() / posix_fadvise()</emphasis> are client side
+          mechanisms that do not pass advice to the filesystem, while
+          <literal>llapi_ladvise()</literal> sends advice or hints to one or
+          more Lustre servers on which the file is stored.  In some cases it may
+          be desirable to use both interfaces.
+          </para>
+      </section>
+      <section remap="h5">
+          <title>Return Values</title>
+          <para><literal>llapi_ladvise</literal> returns:</para>
+          <para><literal>0</literal> On success</para>
+          <para><literal>-1</literal> if an error occurred (in which case, errno
+          is set appropriately).</para>
+      </section>
+      <section remap="h5">
+          <title>Errors</title>
+        <para>
+          <informaltable frame="all">
+            <tgroup cols="2">
+              <colspec colname="c1" colwidth="50*"/>
+              <colspec colname="c2" colwidth="50*"/>
+              <thead>
+                <row>
+                  <entry>
+                    <para><emphasis role="bold">Error</emphasis></para>
+                  </entry>
+                  <entry>
+                    <para><emphasis role="bold">Description</emphasis></para>
+                  </entry>
+                </row>
+              </thead>
+              <tbody>
+                <row>
+                  <entry>
+                    <para> <literal>ENOMEM</literal></para>
+                  </entry>
+                  <entry>
+                    <para>Insufficient memory to complete operation.</para>
+                  </entry>
+                </row>
+                <row>
+                  <entry>
+                    <para> <literal>EINVAL</literal></para>
+                  </entry>
+                  <entry>
+                    <para>One or more invalid arguments are given.</para>
+                  </entry>
+                </row>
+                <row>
+                  <entry>
+                    <para> <literal>EFAULT</literal></para>
+                  </entry>
+                  <entry>
+                    <para>Memory region pointed by
+                    <literal>ladvise</literal> is not properly mapped.
+                    </para>
+                  </entry>
+                </row>
+                <row>
+                  <entry>
+                    <para> <literal>ENOTSUPP</literal></para>
+                  </entry>
+                  <entry>
+                    <para>Advice type is not supported.</para>
+                  </entry>
+                </row>
+              </tbody>
+            </tgroup>
+          </informaltable>
+          </para>
+      </section>
+  </section>
   <section xml:id="dbdoclet.50438215_marker-1297700">
     <title>Example Using the <literal>llapi</literal> Library</title>
     <para>Use <literal>llapi_file_create</literal> to set Lustre software properties for a new file.