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

   1 #ifndef BABELTRACE2_TRACE_IR_CLOCK_SNAPSHOT_H
   2 #define BABELTRACE2_TRACE_IR_CLOCK_SNAPSHOT_H
   3
   4 /*
   5  * Copyright (c) 2010-2019 EfficiOS Inc. and Linux Foundation
   6  *
   7  * Permission is hereby granted, free of charge, to any person obtaining a copy
   8  * of this software and associated documentation files (the "Software"), to deal
   9  * in the Software without restriction, including without limitation the rights
  10  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  11  * copies of the Software, and to permit persons to whom the Software is
  12  * furnished to do so, subject to the following conditions:
  13  *
  14  * The above copyright notice and this permission notice shall be included in
  15  * all copies or substantial portions of the Software.
  16  *
  17  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  18  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  20  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  21  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  22  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  23  * SOFTWARE.
  24  */
  25
  26 #ifndef __BT_IN_BABELTRACE_H
  27 # error "Please include <babeltrace2/babeltrace.h> instead."
  28 #endif
  29
  30 #include <stdint.h>
  31
  32 #include <babeltrace2/types.h>
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 /*!
  39 @defgroup api-tir-cs Clock snapshot
  40 @ingroup api-tir
  41
  42 @brief
  43     Snapshot of a \bt_stream clock.
  44
  45 A <strong><em>clock snapshot</em></strong> is a snapshot of the value
  46 of a \bt_stream clock (a \bt_clock_cls instance).
  47
  48 A clock snapshot is a \ref api-tir "trace IR" data object.
  49
  50 <em>Stream clocks</em> only exist conceptually in \bt_name because they
  51 are stateful objects. \bt_cp_msg cannot refer to stateful objects
  52 because they must not change while being transported from one
  53 \bt_comp to the other.
  54
  55 Instead of having a stream clock object, messages have a default
  56 clock snapshot: this is a snapshot of the value of a stream's
  57 default clock (a clock class instance):
  58
  59 @image html clocks.png
  60
  61 In the illustration above, notice that:
  62
  63 - Each stream has a default clock (yellow bell alarm clock): this is an
  64   instance of the stream's class's default clock class.
  65 - Each \bt_msg (objects in blue stream rectangles) created for a given
  66   stream has a default clock snapshot (yellow star): this is a snapshot
  67   of the stream's default clock.
  68
  69   In other words, a default clock snapshot contains the value of the
  70   stream's default clock when this message occured.
  71
  72 A clock snapshot is a \ref api-fund-unique-object "unique object": it
  73 belongs to a \bt_msg.
  74
  75 The type of a clock snapshot is #bt_clock_snapshot.
  76
  77 You cannot create a clock snapshot: you specify a clock snapshot value
  78 (in clock cycles, a \c uint64_t value) when you create a \bt_msg or set
  79 a message's clock snapshot with one of:
  80
  81 - bt_message_stream_beginning_set_default_clock_snapshot()
  82 - bt_message_stream_end_set_default_clock_snapshot()
  83 - bt_message_event_create_with_default_clock_snapshot()
  84 - bt_message_event_create_with_packet_and_default_clock_snapshot()
  85 - bt_message_packet_beginning_create_with_default_clock_snapshot()
  86 - bt_message_packet_end_create_with_default_clock_snapshot()
  87 - bt_message_discarded_events_create_with_default_clock_snapshots()
  88 - bt_message_discarded_packets_create_with_default_clock_snapshots()
  89 - bt_message_message_iterator_inactivity_create()
  90
  91 See \ref api-tir-clock-cls-origin "Clock value vs. clock class origin"
  92 to understand the meaning of a clock's value in relation to the
  93 properties of its class.
  94 */
  95
  96 /*! @{ */
  97
  98 /*!
  99 @name Type
 100 @{
 101
 102 @typedef struct bt_clock_snapshot bt_clock_snapshot;
 103
 104 @brief
 105     Clock snapshot.
 106
 107 @}
 108 */
 109
 110 /*!
 111 @brief
 112     Borrows the \ref api-tir-clock-cls "class" of the clock of which
 113     \bt_p{clock_snapshot} is a snapshot.
 114
 115 @param[in] clock_snapshot
 116     Clock snapshot of which to borrow the clock class.
 117
 118 @returns
 119     \em Borrowed reference of the clock class of \bt_p{clock_snapshot}.
 120
 121 @bt_pre_not_null{clock_snapshot}
 122 */
 123 extern const bt_clock_class *bt_clock_snapshot_borrow_clock_class_const(
 124                 const bt_clock_snapshot *clock_snapshot);
 125
 126 /*!
 127 @brief
 128     Returns the value, in clock cycles, of the clock snapshot
 129     \bt_p{clock_snapshot}.
 130
 131 @param[in] clock_snapshot
 132     Clock snapshot of which to get the value.
 133
 134 @returns
 135     Value of \bt_p{clock_snapshot} (clock cycles).
 136
 137 @bt_pre_not_null{clock_snapshot}
 138
 139 @sa bt_clock_snapshot_get_ns_from_origin() &mdash;
 140     Returns the equivalent nanoseconds from clock class origin of a
 141     clock snapshot's value.
 142 */
 143 extern uint64_t bt_clock_snapshot_get_value(
 144                 const bt_clock_snapshot *clock_snapshot);
 145
 146 /*!
 147 @brief
 148     Status codes for bt_clock_snapshot_get_ns_from_origin().
 149 */
 150 typedef enum bt_clock_snapshot_get_ns_from_origin_status {
 151         /*!
 152         @brief
 153             Success.
 154         */
 155         BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OK                  = __BT_FUNC_STATUS_OK,
 156
 157         /*!
 158         @brief
 159             Integer overflow while computing the result.
 160         */
 161         BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR      = __BT_FUNC_STATUS_OVERFLOW_ERROR,
 162 } bt_clock_snapshot_get_ns_from_origin_status;
 163
 164 /*!
 165 @brief
 166     Converts the value of the clock snapshot
 167     \bt_p{clock_snapshot} from cycles to nanoseconds from the
 168     \ref api-tir-clock-cls-origin "origin" of its
 169     \bt_clock_cls and sets \bt_p{*ns_from_origin} to the result.
 170
 171 This function:
 172
 173 -# Converts the
 174    \link api-tir-clock-cls-prop-offset "offset in cycles"\endlink
 175    property of the clock class of \bt_p{clock_snapshot} to
 176    seconds using its
 177    \ref api-tir-clock-cls-prop-freq "frequency".
 178 -# Converts the value of \bt_p{clock_snapshot} to seconds using the
 179    frequency of its clock class.
 180 -# Adds the values of 1., 2., and the
 181    \link api-tir-clock-cls-prop-offset "offset in seconds"\endlink
 182    property of the clock class of \bt_p{clock_snapshot}.
 183 -# Converts the value of 3. to nanoseconds and sets
 184    \bt_p{*ns_from_origin} to this result.
 185
 186 The following illustration shows the possible scenarios:
 187
 188 @image html clock-terminology.png
 189
 190 This function can fail and return the
 191 #BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR status
 192 code if any step of the computation process causes an integer overflow.
 193
 194 @param[in] clock_snapshot
 195     Clock snapshot containing the value to convert to nanoseconds
 196     from the origin of its clock class.
 197 @param[out] ns_from_origin
 198     <strong>On success</strong>, \bt_p{*ns_from_origin} is the value
 199     of \bt_p{clock_snapshot} converted to nanoseconds from the origin
 200     of its clock class.
 201
 202 @retval #BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OK
 203     Success.
 204 @retval #BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR
 205     Integer overflow while computing the result.
 206
 207 @bt_pre_not_null{clock_snapshot}
 208 @bt_pre_not_null{ns_from_origin}
 209
 210 @sa bt_util_clock_cycles_to_ns_from_origin() &mdash;
 211     Converts a clock value from cycles to nanoseconds from the clock's
 212     origin.
 213 @sa bt_clock_class_cycles_to_ns_from_origin() &mdash;
 214     Converts a clock value from cycles to nanoseconds from a clock
 215     class's origin.
 216 */
 217 extern bt_clock_snapshot_get_ns_from_origin_status
 218 bt_clock_snapshot_get_ns_from_origin(
 219                 const bt_clock_snapshot *clock_snapshot,
 220                 int64_t *ns_from_origin);
 221
 222 /*! @} */
 223
 224 #ifdef __cplusplus
 225 }
 226 #endif
 227
 228 #endif /* BABELTRACE2_TRACE_IR_CLOCK_SNAPSHOT_H */