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