Move to kernel style SPDX license identifiers
[babeltrace.git] / include / babeltrace2 / trace-ir / clock-snapshot.h
CommitLineData
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
19extern "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
29A <strong><em>clock snapshot</em></strong> is a snapshot of the value
30of a \bt_stream clock (a \bt_clock_cls instance).
31
32A 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
35are stateful objects. \bt_cp_msg cannot refer to stateful objects
36because they must not change while being transported from one
37\bt_comp to the other.
38
39Instead of having a stream clock object, messages have a default
40clock snapshot: this is a snapshot of the value of a stream's
41default clock (a clock class instance):
42
43@image html clocks.png
44
45In 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
56A clock snapshot is a \ref api-fund-unique-object "unique object": it
57belongs to a \bt_msg.
58
59The type of a clock snapshot is #bt_clock_snapshot.
60
61You 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
63a 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
75See \ref api-tir-clock-cls-origin "Clock value vs. clock class origin"
76to understand the meaning of a clock's value in relation to the
77properties 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*/
107extern 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*/
127extern 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*/
134typedef 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
155This 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
170The following illustration shows the possible scenarios:
171
172@image html clock-terminology.png
173
174This function can fail and return the
175#BT_CLOCK_SNAPSHOT_GET_NS_FROM_ORIGIN_STATUS_OVERFLOW_ERROR status
176code 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*/
201extern bt_clock_snapshot_get_ns_from_origin_status
202bt_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 */
This page took 0.034902 seconds and 4 git commands to generate.