LU-4315 doc: split lctl get_param and set_param man pages

[fs/lustre-release.git] / lustre / doc / llapi_ladvise.3

diff --git a/lustre/doc/llapi_ladvise.3 b/lustre/doc/llapi_ladvise.3
index 4ef508d..d755899 100644 (file)
--- a/lustre/doc/llapi_ladvise.3
+++ b/lustre/doc/llapi_ladvise.3
@@ -28,6 +28,9 @@ can modify how the advice will be processed via bitwise-or'd values:
 .B LF_ASYNC
 Client returns to userspace immediately after submitting ladvise RPCs, leaving
 server threads to handle the advices asynchronously.
 .B LF_ASYNC
 Client returns to userspace immediately after submitting ladvise RPCs, leaving
 server threads to handle the advices asynchronously.

+.TP
+.B LF_UNSET
+Unset/clear a previous advice (Currently only supports LU_ADVISE_LOCKNOEXPAND).

 .PP
 Each of the
 .I ladvise
 .PP
 Each of the
 .I ladvise


@@ -58,6 +61,12 @@ Prefetch data into server cache using optimum I/O size for the server.
 .B LU_LADVISE_DONTNEED
 Clean cached data for the specified file range(s) on the server.
 .TP
 .B LU_LADVISE_DONTNEED
 Clean cached data for the specified file range(s) on the server.
 .TP

+.B LU_LADVISE_LOCKAHEAD
+Request an LDLM extent lock of the given mode on the given byte range.
+.TP
+.B LU_LADVISE_NOEXPAND
+Disable extent lock expansion behavior for I/O to this file descriptor.
+.TP

 .I lla_start
 is the offset in bytes for the start of this advice.
 .TP
 .I lla_start
 is the offset in bytes for the start of this advice.
 .TP


@@ -67,6 +76,23 @@ is the offset in bytes (non-inclusive) for the end of this advice.
 .IR lla_value1 , " lla_value2" , " lla_value3" , " lla_value4"
 additional arguments for future advice types and should be
 set to zero if not explicitly required for a given advice type.
 .IR lla_value1 , " lla_value2" , " lla_value3" , " lla_value4"
 additional arguments for future advice types and should be
 set to zero if not explicitly required for a given advice type.

+Advice-specific names for these fields follow.
+.TP
+.IR lla_lockahead_mode
+When using LU_ADVISE_LOCKAHEAD, the 'lla_value1' field is used to
+communicate the requested lock mode, and can be referred to as
+lla_lockahead_mode.
+.TP
+.IR lla_peradvice_flags
+When using advices which support them, the 'lla_value2' field is
+used to communicate per-advice flags and can be referred to as
+lla_peradvice_flags.  Both LF_ASYNC and LF_UNSET are supported
+as peradvice flags.
+.TP
+.IR lla_lockahead_result
+When using LU_ADVISE_LOCKAHEAD, the 'lla_value3' field is used to
+communicate the result of the request, and can be referred to as lla_lockahead_result.
+.PP

 .PP
 .B llapi_ladvise()
 forwards the advice to Lustre servers without guaranteeing how and when
 .PP
 .B llapi_ladvise()
 forwards the advice to Lustre servers without guaranteeing how and when


@@ -86,6 +112,13 @@ that data into each client cache with
 .B fadvise()
 may not be, due to much more data being sent to the clients.
 
 .B fadvise()
 may not be, due to much more data being sent to the clients.
 

+LU_LADVISE_LOCKAHEAD merits a special comment. While it is possible and
+encouraged to use it directly in your application to avoid lock contention
+(primarily for writing to a single file from multiple clients), it will
+also be available in the MPI-I/O / MPICH library from ANL for use with the
+i/o aggregation mode of that library. This is intended (eventually) to be
+the primary way this feature is used.
+

 While conceptually similar to the
 .BR posix_fadvise (2)
 and Linux
 While conceptually similar to the
 .BR posix_fadvise (2)
 and Linux