include/babeltrace2/trace-ir/clock-snapshot.h

   1 /*
   2  * SPDX-License-Identifier: MIT
   3  *
   4  * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation
   5  */
   6
   7 #ifndef BABELTRACE2_TRACE_IR_CLOCK_SNAPSHOT_H
   8 #define BABELTRACE2_TRACE_IR_CLOCK_SNAPSHOT_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 #include <babeltrace2/types.h>
  19
  20 #ifdef __cplusplus
  21 extern "C" {
  22 #endif
  23
  24 /*!
  25 @defgroup api-tir-cs Clock snapshot
  26 @ingroup api-tir
  27
  28 @brief
  29     Snapshot of a \bt_stream clock.
  30
  31 A <strong><em>clock snapshot</em></strong> is a snapshot of the value
  32 of a \bt_stream clock (a \bt_clock_cls instance).
  33
  34 A clock snapshot is a \ref api-tir "trace IR" data object.
  35
  36 <em>Stream clocks</em> only exist conceptually in \bt_name because they
  37 are stateful objects. \bt_cp_msg cannot refer to stateful objects
  38 because they must not change while being transported from one
  39 \bt_comp to the other.
  40
  41 Instead of having a stream clock object, messages have a default
  42 clock snapshot: this is a snapshot of the value of a stream's
  43 default clock (a clock class instance):
  44
  45 @image html clocks.png
  46
  47 In the illustration above, notice that:
  48
  49 - Each stream has a default clock (yellow bell alarm clock): this is an
  50   instance of the stream's class's default clock class.
  51 - Each \bt_msg (objects in blue stream rectangles) created for a given
  52   stream has a default clock snapshot (yellow star): this is a snapshot
  53   of the stream's default clock.
  54
  55   In other words, a default clock snapshot contains the value of the
  56   stream's default clock when this message occurred.
  57
  58 A clock snapshot is a \ref api-fund-unique-object "unique object": it
  59 belongs to a \bt_msg.
  60
  61 The type of a clock snapshot is #bt_clock_snapshot.
  62
  63 You cannot create a clock snapshot: you specify a clock snapshot value
  64 (in clock cycles, a \c uint64_t value) when you create a \bt_msg or set
  65 a message's clock snapshot with one of:
  66
  67 - bt_message_stream_beginning_set_default_clock_snapshot()
  68 - bt_message_stream_end_set_default_clock_snapshot()
  69 - bt_message_event_create_with_default_clock_snapshot()
  70 - bt_message_event_create_with_packet_and_default_clock_snapshot()
  71 - bt_message_packet_beginning_create_with_default_clock_snapshot()
  72 - bt_message_packet_end_create_with_default_clock_snapshot()
  73 - bt_message_discarded_events_create_with_default_clock_snapshots()
  74 - bt_message_discarded_packets_create_with_default_clock_snapshots()
  75 - bt_message_message_iterator_inactivity_create()
  76
  77 See \ref api-tir-clock-cls-origin "Clock value vs. clock class origin"
  78 to understand the meaning of a clock's value in relation to the
  79 properties of its class.
  80 */
  81
  82 /*! @{ */
  83
  84 /*!
  85 @name Type
  86 @{
  87
  88 @typedef struct bt_clock_snapshot bt_clock_snapshot;
  89
  90 @brief
  91     Clock snapshot.
  92
  93 @}
  94 */
  95
  96 /*!
  97 @brief
  98     Borrows the \ref api-tir-clock-cls "class" of the clock of which
  99     \bt_p{clock_snapshot} is a snapshot.
 100
 101 @param[in] clock_snapshot
 102     Clock snapshot of which to borrow the clock class.
 103
 104 @returns
 105     \em Borrowed reference of the clock class of \bt_p{clock_snapshot}.
 106
 107 @bt_pre_not_null{clock_snapshot}
 108 */
 109 extern const bt_clock_class *bt_clock_snapshot_borrow_clock_class_const(
 110                 const bt_clock_snapshot *clock_snapshot) __BT_NOEXCEPT;
 111
 112 /*!
 113 @brief
 114     Returns the value, in clock cycles, of the clock snapshot
 115     \bt_p{clock_snapshot}.
 116
 117 @param[in] clock_snapshot
 118     Clock snapshot of which to get the value.
 119
 120 @returns
 121     Value of \bt_p{clock_snapshot} (clock cycles).
 122
 123 @bt_pre_not_null{clock_snapshot}
 124
 125 @sa bt_clock_snapshot_get_ns_from_origin() &mdash;
 126     Returns the equivalent nanoseconds from clock class origin of a
 127     clock snapshot's value.
 128 */
 129 extern uint64_t bt_clock_snapshot_get_value(
 130                 const bt_clock_snapshot *clock_snapshot) __BT_NOEXCEPT;
 131
 132 /*!
 133 @brief
 134     Status codes for bt_clock_snapshot_get_ns_from_origin().
 135 */
 136 typedef enum bt_clock_snapshot_get_ns_from_origin_status {
 137         /*!
 138         @brief
 139             Success.
 140         */
 141         BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OK                  = __BT_FUNC_STATUS_OK,
 142
 143         /*!
 144         @brief
 145             Integer overflow while computing the result.
 146         */
 147         BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR      = __BT_FUNC_STATUS_OVERFLOW_ERROR,
 148 } bt_clock_snapshot_get_ns_from_origin_status;
 149
 150 /*!
 151 @brief
 152     Converts the value of the clock snapshot
 153     \bt_p{clock_snapshot} from cycles to nanoseconds from the
 154     \ref api-tir-clock-cls-origin "origin" of its
 155     \bt_clock_cls and sets \bt_p{*ns_from_origin} to the result.
 156
 157 This function:
 158
 159 -# Converts the
 160    \link api-tir-clock-cls-prop-offset "offset in cycles"\endlink
 161    property of the clock class of \bt_p{clock_snapshot} to
 162    seconds using its
 163    \ref api-tir-clock-cls-prop-freq "frequency".
 164 -# Converts the value of \bt_p{clock_snapshot} to seconds using the
 165    frequency of its clock class.
 166 -# Adds the values of 1., 2., and the
 167    \link api-tir-clock-cls-prop-offset "offset in seconds"\endlink
 168    property of the clock class of \bt_p{clock_snapshot}.
 169 -# Converts the value of 3. to nanoseconds and sets
 170    \bt_p{*ns_from_origin} to this result.
 171
 172 The following illustration shows the possible scenarios:
 173
 174 @image html clock-terminology.png
 175
 176 This function can fail and return the
 177 #BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR status
 178 code if any step of the computation process causes an integer overflow.
 179
 180 @param[in] clock_snapshot
 181     Clock snapshot containing the value to convert to nanoseconds
 182     from the origin of its clock class.
 183 @param[out] ns_from_origin
 184     <strong>On success</strong>, \bt_p{*ns_from_origin} is the value
 185     of \bt_p{clock_snapshot} converted to nanoseconds from the origin
 186     of its clock class.
 187
 188 @retval #BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OK
 189     Success.
 190 @retval #BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR
 191     Integer overflow while computing the result.
 192
 193 @bt_pre_not_null{clock_snapshot}
 194 @bt_pre_not_null{ns_from_origin}
 195
 196 @sa bt_util_clock_cycles_to_ns_from_origin() &mdash;
 197     Converts a clock value from cycles to nanoseconds from the clock's
 198     origin.
 199 @sa bt_clock_class_cycles_to_ns_from_origin() &mdash;
 200     Converts a clock value from cycles to nanoseconds from a clock
 201     class's origin.
 202 */
 203 extern bt_clock_snapshot_get_ns_from_origin_status
 204 bt_clock_snapshot_get_ns_from_origin(
 205                 const bt_clock_snapshot *clock_snapshot,
 206                 int64_t *ns_from_origin) __BT_NOEXCEPT;
 207
 208 /*! @} */
 209
 210 #ifdef __cplusplus
 211 }
 212 #endif
 213
 214 #endif /* BABELTRACE2_TRACE_IR_CLOCK_SNAPSHOT_H */