These changes are the raw update to linux-4.4.6-rt14. Kernel sources

[kvmfornfv.git] / kernel / Documentation / device-mapper / statistics.txt

diff --git a/kernel/Documentation/device-mapper/statistics.txt b/kernel/Documentation/device-mapper/statistics.txt
index 2a1673a..6f5ef94 100644 (file)
--- a/kernel/Documentation/device-mapper/statistics.txt
+++ b/kernel/Documentation/device-mapper/statistics.txt
@@ -13,9 +13,14 @@ the range specified.
 The I/O statistics counters for each step-sized area of a region are
 in the same format as /sys/block/*/stat or /proc/diskstats (see:
 Documentation/iostats.txt).  But two extra counters (12 and 13) are
-provided: total time spent reading and writing in milliseconds.         All
-these counters may be accessed by sending the @stats_print message to
-the appropriate DM device via dmsetup.
+provided: total time spent reading and writing.  When the histogram
+argument is used, the 14th parameter is reported that represents the
+histogram of latencies.  All these counters may be accessed by sending
+the @stats_print message to the appropriate DM device via dmsetup.
+
+The reported times are in milliseconds and the granularity depends on
+the kernel ticks.  When the option precise_timestamps is used, the
+reported times are in nanoseconds.
 
 Each region has a corresponding unique identifier, which we call a
 region_id, that is assigned when the region is created.         The region_id
@@ -33,7 +38,9 @@ memory is used by reading
 Messages
 ========
 
-    @stats_create <range> <step> [<program_id> [<aux_data>]]
+    @stats_create <range> <step>
+               [<number_of_optional_arguments> <optional_arguments>...]
+               [<program_id> [<aux_data>]]
 
        Create a new region and return the region_id.
 
@@ -48,6 +55,29 @@ Messages
          "/<number_of_areas>" - the range is subdivided into the specified
                                 number of areas.
 
+       <number_of_optional_arguments>
+         The number of optional arguments
+
+       <optional_arguments>
+         The following optional arguments are supported
+         precise_timestamps - use precise timer with nanosecond resolution
+               instead of the "jiffies" variable.  When this argument is
+               used, the resulting times are in nanoseconds instead of
+               milliseconds.  Precise timestamps are a little bit slower
+               to obtain than jiffies-based timestamps.
+         histogram:n1,n2,n3,n4,... - collect histogram of latencies.  The
+               numbers n1, n2, etc are times that represent the boundaries
+               of the histogram.  If precise_timestamps is not used, the
+               times are in milliseconds, otherwise they are in
+               nanoseconds.  For each range, the kernel will report the
+               number of requests that completed within this range. For
+               example, if we use "histogram:10,20,30", the kernel will
+               report four numbers a:b:c:d. a is the number of requests
+               that took 0-10 ms to complete, b is the number of requests
+               that took 10-20 ms to complete, c is the number of requests
+               that took 20-30 ms to complete and d is the number of
+               requests that took more than 30 ms to complete.
+
        <program_id>
          An optional parameter.  A name that uniquely identifies
          the userspace owner of the range.  This groups ranges together
@@ -55,6 +85,9 @@ Messages
          created and ignore those created by others.
          The kernel returns this string back in the output of
          @stats_list message, but it doesn't use it for anything else.
+         If we omit the number of optional arguments, program id must not
+         be a number, otherwise it would be interpreted as the number of
+         optional arguments.
 
        <aux_data>
          An optional parameter.  A word that provides auxiliary data
@@ -88,6 +121,10 @@ Messages
 
        Output format:
          <region_id>: <start_sector>+<length> <step> <program_id> <aux_data>
+               precise_timestamps histogram:n1,n2,n3,...
+
+       The strings "precise_timestamps" and "histogram" are printed only
+       if they were specified when creating the region.
 
     @stats_print <region_id> [<starting_line> <number_of_lines>]