Commit | Line | Data |
---|---|---|
43c59509 | 1 | /* |
0235b0db | 2 | * SPDX-License-Identifier: MIT |
43c59509 | 3 | * |
0235b0db | 4 | * Copyright (C) 2010-2019 EfficiOS Inc. and Linux Foundation |
43c59509 PP |
5 | */ |
6 | ||
0235b0db MJ |
7 | #ifndef BABELTRACE2_TRACE_IR_CLOCK_SNAPSHOT_H |
8 | #define BABELTRACE2_TRACE_IR_CLOCK_SNAPSHOT_H | |
9 | ||
f38da6ca SM |
10 | /* IWYU pragma: private, include <babeltrace2/babeltrace.h> */ |
11 | ||
43c59509 PP |
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 | |
118ae153 | 56 | stream's default clock when this message occurred. |
43c59509 PP |
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( | |
4c81a2b7 | 110 | const bt_clock_snapshot *clock_snapshot) __BT_NOEXCEPT; |
43c59509 PP |
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() — | |
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( | |
4c81a2b7 | 130 | const bt_clock_snapshot *clock_snapshot) __BT_NOEXCEPT; |
43c59509 PP |
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() — | |
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() — | |
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, | |
4c81a2b7 | 206 | int64_t *ns_from_origin) __BT_NOEXCEPT; |
43c59509 PP |
207 | |
208 | /*! @} */ | |
209 | ||
210 | #ifdef __cplusplus | |
211 | } | |
212 | #endif | |
213 | ||
214 | #endif /* BABELTRACE2_TRACE_IR_CLOCK_SNAPSHOT_H */ |