Commit | Line | Data |
---|---|---|
43c59509 PP |
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 | |
118ae153 | 70 | stream's default clock when this message occurred. |
43c59509 PP |
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() — | |
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() — | |
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() — | |
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 */ |