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