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 <stdint.h>
  27 #include <time.h>
  28 #include <string.h>
  29 #include <stdio.h>
  30 #include <lttng/ust-clock.h>
  31
  32 /*
  33  * For sake of example, transform time into a coarse clock (freq: 1KHz).
  34  * Note that division can be slow on some architectures. Should be
  35  * avoided. Use shift and multiplication instead. e.g.:
  36  *
  37  * Operation: / 1000000ULL
  38  * 1/1000000ULL = .000001
  39  * 2^19 < 1000000 < 2^20
  40  * Add a 10 bits shift to increase accuracy:
  41  * 2^(19+10) = 536870912
  42  * x * 1 / 2^(19+10) ~= .000001
  43  * 537 * 1 / 2^29 = .00000100024044513702
  44  * 537 (multiplication factor) is between 2^9 and 2^10.
  45  *
  46  * In order not to overflow, first right shift by 10, multiply, and right
  47  * shift by 19.
  48  */
  49 #define DIV_CLOCK_SHIFT1        10
  50 #define DIV_CLOCK_MUL           537
  51 #define DIV_CLOCK_SHIFT2        19
  52
  53 static
  54 uint64_t plugin_read64(void)
  55 {
  56         struct timespec ts;
  57
  58         clock_gettime(CLOCK_MONOTONIC, &ts);
  59         /*
  60          * This is a rather dumb example, but it illustrates the plugin
  61          * mechanism: we take the monotonic clock, and transform it into
  62          * a very coarse clock, which increment only at 1KHz frequency.
  63          */
  64         return ((uint64_t) ts.tv_sec * 1000ULL)
  65                 + ((DIV_CLOCK_MUL * ((uint64_t) ts.tv_nsec >> DIV_CLOCK_SHIFT1))
  66                         >> DIV_CLOCK_SHIFT2);
  67 }
  68
  69 static
  70 uint64_t plugin_freq(void)
  71 {
  72         return 1000;    /* 1KHz clock (very coarse!) */
  73 }
  74
  75 static
  76 int plugin_uuid(char *uuid)
  77 {
  78         const char myuuid[] = "123456789012345678901234567890123456";
  79
  80         /*
  81          * Should read some unique identifier for this clock shared
  82          * across all components of the system using this clock for
  83          * tracing.
  84          */
  85         memcpy(uuid, myuuid, LTTNG_UST_UUID_STR_LEN);
  86         return 0;
  87 }
  88
  89 static
  90 const char *plugin_name(void)
  91 {
  92         return "my_example_clock";
  93 }
  94
  95 static
  96 const char *plugin_description(void)
  97 {
  98         return "Coarse monotonic clock at 1KHz";
  99 }
 100
 101 void lttng_ust_clock_plugin_init(void)
 102 {
 103         int ret;
 104
 105         ret = lttng_ust_trace_clock_set_read64_cb(plugin_read64);
 106         if (ret) {
 107                 fprintf(stderr, "Error setting clock override read64 callback: %s\n",
 108                         strerror(-ret));
 109                 goto error;
 110         }
 111         ret = lttng_ust_trace_clock_set_freq_cb(plugin_freq);
 112         if (ret) {
 113                 fprintf(stderr, "Error setting clock override freq callback: %s\n",
 114                         strerror(-ret));
 115                 goto error;
 116         }
 117         ret = lttng_ust_trace_clock_set_uuid_cb(plugin_uuid);
 118         if (ret) {
 119                 fprintf(stderr, "Error setting clock override uuid callback: %s\n",
 120                         strerror(-ret));
 121                 goto error;
 122         }
 123
 124         ret = lttng_ust_trace_clock_set_name_cb(plugin_name);
 125         if (ret) {
 126                 fprintf(stderr, "Error setting clock override name callback: %s\n",
 127                         strerror(-ret));
 128                 goto error;
 129         }
 130
 131         ret = lttng_ust_trace_clock_set_description_cb(plugin_description);
 132         if (ret) {
 133                 fprintf(stderr, "Error setting clock override description callback: %s\n",
 134                         strerror(-ret));
 135                 goto error;
 136         }
 137
 138         ret = lttng_ust_enable_trace_clock_override();
 139         if (ret) {
 140                 fprintf(stderr, "Error enabling clock override: %s\n",
 141                         strerror(-ret));
 142                 goto error;
 143         }
 144
 145         return;
 146
 147 error:
 148         exit(EXIT_FAILURE);
 149 }