include/babeltrace2/util.h

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
   5  */
   6
   7 #ifndef BABELTRACE2_UTIL_H
   8 #define BABELTRACE2_UTIL_H
   9
  10 #ifndef __BT_IN_BABELTRACE_H
  11 # error "Please include <babeltrace2/babeltrace.h> instead."
  12 #endif
  13
  14 #include <stdint.h>
  15
  16 #ifdef __cplusplus
  17 extern "C" {
  18 #endif
  19
  20 /*!
  21 @defgroup api-util General purpose utilities
  22
  23 @brief
  24     General purpose utilities.
  25
  26 This module contains general purpose utilities.
  27 */
  28
  29 /*! @{ */
  30
  31 /*!
  32 @brief
  33     Status codes for bt_util_clock_cycles_to_ns_from_origin().
  34 */
  35 typedef enum bt_util_clock_cycles_to_ns_from_origin_status {
  36         /*!
  37         @brief
  38             Success.
  39         */
  40         BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK                = __BT_FUNC_STATUS_OK,
  41
  42         /*!
  43         @brief
  44             Integer overflow while computing the result.
  45         */
  46         BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR    = __BT_FUNC_STATUS_OVERFLOW_ERROR,
  47 } bt_util_clock_cycles_to_ns_from_origin_status;
  48
  49 /*!
  50 @brief
  51     Converts the clock value \bt_p{cycles} from cycles to nanoseconds
  52     from the clock's origin and sets \bt_p{*ns_from_origin} to the
  53     result.
  54
  55 This function considers the clock's frequency in Hz (\bt_p{frequency}),
  56 an offset from its origin in seconds (\bt_p{offset_seconds}) which
  57 can be negative, and an additional offset in cycles
  58 (\bt_p{offset_cycles}).
  59
  60 This function:
  61
  62 -# Converts the \bt_p{offset_cycles} value to seconds using
  63    \bt_p{frequency}.
  64 -# Converts the \bt_p{cycles} value to seconds using \bt_p{frequency}.
  65 -# Adds the values of 1., 2., and \bt_p{offset_seconds}.
  66 -# Converts the value of 3. to nanoseconds and sets
  67    \bt_p{*ns_from_origin} to this result.
  68
  69 The following illustration shows the possible scenarios:
  70
  71 @image html clock-terminology.png
  72
  73 \bt_p{offset_seconds} can be negative. For example, considering:
  74
  75 - A 1000&nbsp;Hz clock.
  76 - \bt_p{offset_seconds} set to -10&nbsp;seconds.
  77 - \bt_p{offset_cycles} set to 500&nbsp;cycles
  78   (that is, 0.5&nbsp;seconds).
  79 - \bt_p{cycles} set to 2000&nbsp;cycles (that is, 2&nbsp;seconds).
  80
  81 The computed value is -7.5&nbsp;seconds, so this function sets
  82 \bt_p{*ns_from_origin} to -7,500,000,000.
  83
  84 This function can fail and return the
  85 #BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR status
  86 code if any step of the computation process causes an integer overflow.
  87
  88 @param[in] cycles
  89     Clock's value (cycles).
  90 @param[in] frequency
  91     Clock's frequency (Hz, or cycles/second).
  92 @param[in] offset_seconds
  93     Offset, in seconds, from the clock's origin to add to
  94     \bt_p{cycles} (once converted to seconds).
  95 @param[in] offset_cycles
  96     Offset, in cycles, to add to \bt_p{cycles}.
  97 @param[out] ns_from_origin
  98     <strong>On success</strong>, \bt_p{*ns_from_origin} is \bt_p{cycles}
  99     converted to nanoseconds from origin considering the clock's
 100     properties.
 101
 102 @retval #BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OK
 103     Success.
 104 @retval #BT_UTIL_CLOCK_CYCLES_TO_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR
 105     Integer overflow while computing the result.
 106
 107 @pre
 108     \bt_p{frequency} is not 0.
 109 @pre
 110     \bt_p{frequency} is not <code>UINT64_C(-1)</code>.
 111 @pre
 112     \bt_p{frequency} is greater than \bt_p{offset_cycles}.
 113 @pre
 114     \bt_p{offset_cycles} is less than \bt_p{frequency}.
 115 @bt_pre_not_null{ns_from_origin}
 116
 117 @sa bt_clock_class_cycles_to_ns_from_origin() &mdash;
 118     Converts a stream clock value from cycles to nanoseconds from the
 119     origin of a given clock class.
 120 */
 121 bt_util_clock_cycles_to_ns_from_origin_status
 122 bt_util_clock_cycles_to_ns_from_origin(uint64_t cycles,
 123                 uint64_t frequency, int64_t offset_seconds,
 124                 uint64_t offset_cycles, int64_t *ns_from_origin);
 125
 126 /*! @} */
 127
 128 #ifdef __cplusplus
 129 }
 130 #endif
 131
 132 #endif /* BABELTRACE2_UTIL_H */