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