doc/examples/clock-override/lttng-ust-clock-override-example.c

   1 /*
   2  * lttng-clock-override-example.c
   3  *
   4  * Copyright (c) 2014 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
   5  *
   6  * Permission is hereby granted, free of charge, to any person obtaining a copy
   7  * of this software and associated documentation files (the "Software"), to deal
   8  * in the Software without restriction, including without limitation the rights
   9  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  10  * copies of the Software, and to permit persons to whom the Software is
  11  * furnished to do so, subject to the following conditions:
  12  *
  13  * The above copyright notice and this permission notice shall be included in
  14  * all copies or substantial portions of the Software.
  15  *
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  21  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  22  * SOFTWARE.
  23  */
  24
  25 #include <stdlib.h>
  26 #include <time.h>
  27 #include <string.h>
  28 #include <stdio.h>
  29 #include <lttng/ust-clock.h>
  30
  31 /*
  32  * For sake of example, transform time into a coarse clock (freq: 1KHz).
  33  * Note that division can be slow on some architectures. Should be
  34  * avoided. Use shift and multiplication instead. e.g.:
  35  *
  36  * Operation: / 1000000ULL
  37  * 1/1000000ULL = .000001
  38  * 2^19 < 1000000 < 2^20
  39  * Add a 10 bits shift to increase accuracy:
  40  * 2^(19+10) = 536870912
  41  * x * 1 / 2^(19+10) ~= .000001
  42  * 537 * 1 / 2^29 = .00000100024044513702
  43  * 537 (multiplication factor) is between 2^9 and 2^10.
  44  *
  45  * In order not to overflow, first right shift by 10, multiply, and right
  46  * shift by 19.
  47  */
  48 #define DIV_CLOCK_SHIFT1        10
  49 #define DIV_CLOCK_MUL           537
  50 #define DIV_CLOCK_SHIFT2        19
  51
  52 static
  53 uint64_t plugin_read64(void)
  54 {
  55         struct timespec ts;
  56
  57         clock_gettime(CLOCK_MONOTONIC, &ts);
  58         /*
  59          * This is a rather dumb example, but it illustrates the plugin
  60          * mechanism: we take the monotonic clock, and transform it into
  61          * a very coarse clock, which increment only at 1KHz frequency.
  62          */
  63         return ((uint64_t) ts.tv_sec * 1000ULL)
  64                 + ((DIV_CLOCK_MUL * ((uint64_t) ts.tv_nsec >> DIV_CLOCK_SHIFT1))
  65                         >> DIV_CLOCK_SHIFT2);
  66 }
  67
  68 static
  69 uint64_t plugin_freq(void)
  70 {
  71         return 1000;    /* 1KHz clock (very coarse!) */
  72 }
  73
  74 static
  75 int plugin_uuid(char *uuid)
  76 {
  77         const char myuuid[] = "123456789012345678901234567890123456";
  78
  79         /*
  80          * Should read some unique identifier for this clock shared
  81          * across all components of the system using this clock for
  82          * tracing.
  83          */
  84         memcpy(uuid, myuuid, LTTNG_UST_UUID_STR_LEN);
  85         return 0;
  86 }
  87
  88 static
  89 const char *plugin_name(void)
  90 {
  91         return "my_example_clock";
  92 }
  93
  94 static
  95 const char *plugin_description(void)
  96 {
  97         return "Coarse monotonic clock at 1KHz";
  98 }
  99
 100 void lttng_ust_clock_plugin_init(void)
 101 {
 102         int ret;
 103
 104         ret = lttng_ust_trace_clock_set_read64_cb(plugin_read64);
 105         if (ret) {
 106                 fprintf(stderr, "Error setting clock override read64 callback: %s\n",
 107                         strerror(-ret));
 108                 goto error;
 109         }
 110         ret = lttng_ust_trace_clock_set_freq_cb(plugin_freq);
 111         if (ret) {
 112                 fprintf(stderr, "Error setting clock override freq callback: %s\n",
 113                         strerror(-ret));
 114                 goto error;
 115         }
 116         ret = lttng_ust_trace_clock_set_uuid_cb(plugin_uuid);
 117         if (ret) {
 118                 fprintf(stderr, "Error setting clock override uuid callback: %s\n",
 119                         strerror(-ret));
 120                 goto error;
 121         }
 122
 123         ret = lttng_ust_trace_clock_set_name_cb(plugin_name);
 124         if (ret) {
 125                 fprintf(stderr, "Error setting clock override name callback: %s\n",
 126                         strerror(-ret));
 127                 goto error;
 128         }
 129
 130         ret = lttng_ust_trace_clock_set_description_cb(plugin_description);
 131         if (ret) {
 132                 fprintf(stderr, "Error setting clock override description callback: %s\n",
 133                         strerror(-ret));
 134                 goto error;
 135         }
 136
 137         ret = lttng_ust_enable_trace_clock_override();
 138         if (ret) {
 139                 fprintf(stderr, "Error enabling clock override: %s\n",
 140                         strerror(-ret));
 141                 goto error;
 142         }
 143
 144         return;
 145
 146 error:
 147         exit(EXIT_FAILURE);
 148 }