New 'hist' APIs have been added and some existing APIs have been
modified. Here we update the documentation accordingly.
Signed-off-by: Yordan Karadzhov (VMware) <y.karadz@xxxxxxxxx>
---
Documentation/libtracefs-hist-cont.txt | 30 ++++++++--
Documentation/libtracefs-hist.txt | 80 +++++++++++++++-----------
2 files changed, 69 insertions(+), 41 deletions(-)
diff --git a/Documentation/libtracefs-hist-cont.txt b/Documentation/libtracefs-hist-cont.txt
index 1b0153c..2ee830d 100644
--- a/Documentation/libtracefs-hist-cont.txt
+++ b/Documentation/libtracefs-hist-cont.txt
@@ -11,18 +11,36 @@ SYNOPSIS
--
*#include <tracefs.h>*
-int tracefs_hist_pause(struct tracefs_hist pass:[*]hist);
-int tracefs_hist_continue(struct tracefs_hist pass:[*]hist);
-int tracefs_hist_reset(struct tracefs_hist pass:[*]hist);
+int tracefs_hist_start(struct tracefs_instance pass:[*]instance, struct tracefs_hist pass:[*]hist);
+int tracefs_hist_destory(struct tracefs_instance pass:[*]instance, struct tracefs_hist pass:[*]hist);
+int tracefs_hist_pause(struct tracefs_instance pass:[*]instance, struct tracefs_hist pass:[*]hist);
+int tracefs_hist_continue(struct tracefs_instance pass:[*]instance, struct tracefs_hist pass:[*]hist);
+int tracefs_hist_reset(struct tracefs_instance pass:[*]instance, struct tracefs_hist pass:[*]hist);
+
--
DESCRIPTION
-----------
+
+*tracefs_hist_start* is called to actually start the histogram _hist_.
+The _instance_ is the instance to start the histogram in, NULL if it
+should start at the top level.
+
*tracefs_hist_pause* is called to pause the histogram _hist_.
+The _instance_ is the instance to pause the histogram in, NULL if it
+is in the top level.
*tracefs_hist_continue* is called to continue a paused histogram _hist_.
+The _instance_ is the instance to continue the histogram, NULL if it
+is in the top level.
*tracefs_hist_reset* is called to clear / reset the histogram _hist_.
+The _instance_ is the instance to clear the histogram, NULL if it
+is in the top level.
+
+*tracefs_hist_destory* is called to delete the histogram where it will no longer
+exist. The _instance_ is the instance to delete the histogram from, NULL if it
+is in the top level.
RETURN VALUE
------------
@@ -83,14 +101,14 @@ int main (int argc, char **argv, char **env)
}
hist = tracefs_hist_alloc(instance, "kmem", "kmalloc",
- "call_site", TRACEFS_HIST_KEY_SYM);
+ "call_site", TRACEFS_HIST_KEY_SYM,
+ "bytes_req", 0);
if (!hist) {
fprintf(stderr, "Failed hist create\n");
exit(-1);
}
- ret = tracefs_hist_add_key(hist, "bytes_req", 0);
- ret |= tracefs_hist_add_value(hist, "bytes_alloc");
+ ret = tracefs_hist_add_value(hist, "bytes_alloc");
ret |= tracefs_hist_add_sort_key(hist, "bytes_req", "bytes_alloc", NULL);
ret |= tracefs_hist_sort_key_direction(hist, "bytes_alloc",
diff --git a/Documentation/libtracefs-hist.txt b/Documentation/libtracefs-hist.txt
index 03ac077..0139ba8 100644
--- a/Documentation/libtracefs-hist.txt
+++ b/Documentation/libtracefs-hist.txt
@@ -4,7 +4,7 @@ libtracefs(3)
NAME
----
tracefs_hist_alloc, tracefs_hist_free, tracefs_hist_add_key, tracefs_hist_add_value, tracefs_hist_add_name, tracefs_hist_start,
-tracefs_hist_destory, tracefs_hist_add_sort_key, tracefs_hist_sort_key_direction - Create and update event histograms
+tracefs_hist_destory, tracefs_hist_add_sort_key, tracefs_hist_reset_sort_key,tracefs_hist_sort_key_direction - Create and update event histograms
SYNOPSIS
--------
@@ -12,15 +12,24 @@ SYNOPSIS
--
*#include <tracefs.h>*
-struct tracefs_hist pass:[*]tracefs_hist_alloc(struct tracefs_tep pass:[*] tep,
+struct tracefs_hist pass:[*]tracefs_hist1d_alloc(struct tracefs_tep pass:[*] tep,
const char pass:[*]system, const char pass:[*]event,
const char pass:[*]key, enum tracefs_hist_key_type type);
+struct tracefs_hist pass:[*]tracefs_hist2d_alloc(struct tracefs_tep pass:[*] tep,
+ const char pass:[*]system, const char pass:[*]event,
+ const char pass:[*]key1, enum tracefs_hist_key_type type1,
+ const char pass:[*]key2, enum tracefs_hist_key_type type2));
+struct tracefs_hist pass:[*]tracefs_hist_alloc(struct tracefs_tep pass:[*] tep,
+ const char pass:[*]system, const char pass:[*]event,
+ struct tracefs_hist_axis [*]axes);
void tracefs_hist_free(struct tracefs_hist pass:[*]hist);
int tracefs_hist_add_key(struct tracefs_hist pass:[*]hist, const char pass:[*]key,
enum tracefs_hist_key_type type);
int tracefs_hist_add_value(struct tracefs_hist pass:[*]hist, const char pass:[*]value);
int tracefs_hist_add_sort_key(struct tracefs_hist pass:[*]hist,
- const char pass:[*]sort_key, ...);
+ const char pass:[*]sort_key);
+int tracefs_hist_reset_sort_key(struct tracefs_hist pass:[*]hist,
+ const char pass:[*]sort_key, ...);
int tracefs_hist_sort_key_direction(struct tracefs_hist pass:[*]hist,
const char pass:[*]sort_key,
enum tracefs_hist_sort_direction dir);
@@ -36,8 +45,7 @@ int tracefs_hist_show(struct trace_seq pass:[*]s, struct tracefs_instance pass:[
int tracefs_hist_command(struct tracefs_instance pass:[*]instance,
struct tracefs_hist pass:[*]hist,
enum tracefs_hist_command command);
-int tracefs_hist_start(struct tracefs_instance pass:[*]instance, struct tracefs_hist pass:[*]hist);
-int tracefs_hist_destory(struct tracefs_instance pass:[*]instance, struct tracefs_hist pass:[*]hist);
+
--
DESCRIPTION
@@ -47,14 +55,31 @@ The syntax can be complex and difficult to get correct. This API handles the
syntax, and facilitates the creation and interaction with the event histograms.
See https://www.kernel.org/doc/html/latest/trace/histogram.html for more information.
-*tracefs_hist_alloc*() allocates a "struct tracefs_hist" descriptor and returns
-the address of it. This descriptor must be freed by *tracefs_hist_free*().
+*tracefs_hist1d_alloc*() allocates a "struct tracefs_hist" descriptor of a one-dimensional
+histogram and returns the address of it. This descriptor must be freed by *tracefs_hist_free*().
The _tep_ is a trace event handle (see *tracefs_local_events*(3)), that holds the
_system_ and _event_ that the histogram will be attached to. The _system_ is the
system or group of the event. The _event_ is the event to attach the histogram to.
-The _key_ is a field of the event that will be used as the key of the histogram.
+The _key_ is a field of the event that will be used as the key(dimension) of the histogram.
The _type_ is the type of the _key_. See KEY TYPES below.
+*tracefs_hist2d_alloc*() allocates a "struct tracefs_hist" descriptor of a two-dimensional
+histogram and returns the address of it. This descriptor must be freed by *tracefs_hist_free*().
+The _tep_ is a trace event handle (see *tracefs_local_events*(3)), that holds the
+_system_ and _event_ that the histogram will be attached to. The _system_ is the
+system or group of the event. The _event_ is the event to attach the histogram to.
+The _key1_ is the first field of the event that will be used as the key(dimension)
+of the histogram. The _type1_ is the type of the _key1_. See KEY TYPES below.
+The _key2_ is the second field of the event that will be used as the key(dimension)
+of the histogram. The _type2_ is the type of the _key2_. See KEY TYPES below.
+
+*tracefs_hist_alloc*() allocates a "struct tracefs_hist" descriptor of an N-dimensional
+histogram and returns the address of it. This descriptor must be freed by *tracefs_hist_free*().
+The _tep_ is a trace event handle (see *tracefs_local_events*(3)), that holds the
+_system_ and _event_ that the histogram will be attached to. The _system_ is the
+system or group of the event. The _event_ is the event to attach the histogram to.
+The _axes_ is an array of _key_ / _type_ pairs, defining the dimentions of the histogram.
+
*tracefs_hist_free*() frees the _tracefs_hist_ descriptor. Note, it does not stop
or disable the running histogram if it was started. *tracefs_hist_destroy*() needs
to be called to do so.
@@ -73,8 +98,14 @@ key was hit. The _hist_ is the histogram descriptor to add the value to.
The _value_ is a field in the histogram to add to when an instane of the
key is hit.
-*tracefs_hist_add_sort_key*() will add a key to sort on. Th _hist_ is the
-the histrogram descriptor to add the sort key to. The _sort_key_ is a string
+*tracefs_hist_add_sort_key*() will add a key to sort on. The _hist_ is the
+histrogram descriptor to add the sort key to. The _sort_key_ is a string
+that must match either an already defined key of the histogram, or an already
+defined value. If _hist_ already has sorting keys (previously added) the new
+_sort_key_ will have lower priority(be secondary or so on) when sorting.
+
+*tracefs_hist_reset_sort_key*() will reset the list of key to sort on. The _hist_ is
+the histrogram descriptor to reset the sort key to. The _sort_key_ is a string
that must match either an already defined key of the histogram, or an already
defined value. Multiple sort keys may be added to denote a secondary, sort order
and so on, but all sort keys must match an existing key or value, or be
@@ -146,27 +177,6 @@ The _cmd_ can be one of:
The below functions are wrappers to tracefs_hist_command() to make the
calling conventions a bit easier to understand what is happening.
-*tracefs_hist_start* is called to actually start the histogram _hist_.
-The _instance_ is the instance to start the histogram in, NULL if it
-should start at the top level.
-
-*tracefs_hist_pause* is called to pause the histogram _hist_.
-The _instance_ is the instance to pause the histogram in, NULL if it
-is in the top level.
-
-*tracefs_hist_continue* is called to continue a paused histogram _hist_.
-The _instance_ is the instance to continue the histogram, NULL if it
-is in the top level.
-
-*tracefs_hist_reset* is called to clear / reset the histogram _hist_.
-The _instance_ is the instance to clear the histogram, NULL if it
-is in the top level.
-
-*tracefs_hist_destory* is called to delete the histogram where it will no longer
-exist. The _instance_ is the instance to delete the histogram from, NULL if it
-is in the top level.
-
-
KEY TYPES
---------
@@ -263,15 +273,15 @@ int main (int argc, char **argv, char **env)
}
tep = tracefs_local_events(NULL);
- hist = tracefs_hist_alloc(tep, "kmem", "kmalloc",
- "call_site", TRACEFS_HIST_KEY_SYM);
+ hist = tracefs_hist2d_alloc(tep, "kmem", "kmalloc",
+ "call_site", TRACEFS_HIST_KEY_SYM,
+ "bytes_req", 0);
if (!hist) {
fprintf(stderr, "Failed hist create\n");
exit(-1);
}
- ret = tracefs_hist_add_key(hist, "bytes_req", 0);
- ret |= tracefs_hist_add_value(hist, "bytes_alloc");
+ ret = tracefs_hist_add_value(hist, "bytes_alloc");
ret |= tracefs_hist_add_sort_key(hist, "bytes_req", "bytes_alloc", NULL);
ret |= tracefs_hist_sort_key_direction(hist, "bytes_alloc",
--
2.30.2
|