2 * Copyright (c) 2014-2018, Intel Corporation
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions are met:
7 * * Redistributions of source code must retain the above copyright notice,
8 * this list of conditions and the following disclaimer.
9 * * Redistributions in binary form must reproduce the above copyright notice,
10 * this list of conditions and the following disclaimer in the documentation
11 * and/or other materials provided with the distribution.
12 * * Neither the name of Intel Corporation nor the names of its contributors
13 * may be used to endorse or promote products derived from this software
14 * without specific prior written permission.
16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26 * POSSIBILITY OF SUCH DAMAGE.
42 /* Intel(R) Processor Trace timing. */
44 /* The estimated Time Stamp Count. */
47 /* The base Time Stamp Count (from TSC and MTC). */
50 /* The estimated Fast Counter. */
53 /* The adjusted last CTC value (from MTC and TMA). */
56 /* The adjusted CTC value when @fc was cleared (from MTC and TMA). */
59 /* The number of lost MTC updates. */
62 /* The number of lost CYC updates. */
65 /* The core:bus ratio. */
68 /* A flag saying whether we have seen a TSC packet. */
71 /* A flag saying whether we have seen a CBR packet. */
74 /* A flag saying whether we have seen a TMA packet. */
77 /* A flag saying whether we have seen a MTC packet. */
81 /* Initialize (or reset) the time. */
82 extern void pt_time_init(struct pt_time *time);
84 /* Query the current time.
86 * Provides the estimated Time Stamp Count value in @tsc.
88 * If @lost_mtc is not NULL, provides the number of lost MTC packets.
89 * If @lost_cyc is not NULL, provides the number of lost CYC packets.
91 * Returns zero on success; a negative error code, otherwise.
92 * Returns -pte_internal if @tsc or @time is NULL.
93 * Returns -pte_no_time if there has not been a TSC packet.
95 extern int pt_time_query_tsc(uint64_t *tsc, uint32_t *lost_mtc,
96 uint32_t *lost_cyc, const struct pt_time *time);
98 /* Query the current core:bus ratio.
100 * Provides the core:bus ratio in @cbr.
102 * Returns zero on success; a negative error code, otherwise.
103 * Returns -pte_internal if @cbr or @time is NULL.
104 * Returns -pte_no_cbr if there has not been a CBR packet.
106 extern int pt_time_query_cbr(uint32_t *cbr, const struct pt_time *time);
108 /* Update the time based on an Intel PT packet.
110 * Returns zero on success.
111 * Returns a negative error code, otherwise.
113 extern int pt_time_update_tsc(struct pt_time *, const struct pt_packet_tsc *,
114 const struct pt_config *);
115 extern int pt_time_update_cbr(struct pt_time *, const struct pt_packet_cbr *,
116 const struct pt_config *);
117 extern int pt_time_update_tma(struct pt_time *, const struct pt_packet_tma *,
118 const struct pt_config *);
119 extern int pt_time_update_mtc(struct pt_time *, const struct pt_packet_mtc *,
120 const struct pt_config *);
121 /* @fcr is the fast-counter:cycles ratio obtained by calibration. */
122 extern int pt_time_update_cyc(struct pt_time *, const struct pt_packet_cyc *,
123 const struct pt_config *, uint64_t fcr);
126 /* Timing calibration.
128 * Used for estimating the Fast-Counter:Cycles ratio.
130 * Ideally, we calibrate by counting CYCs between MTCs. Lacking MTCs, we
134 /* The estimated fast-counter:cycles ratio. */
137 /* The minimal and maximal @fcr values. */
138 uint64_t min_fcr, max_fcr;
140 /* The last TSC value.
142 * Used for calibrating at TSC.
146 /* The number of cycles since the last TSC (from CYC).
148 * Used for calibrating at TSC.
152 /* The number of cycles since the last MTC (from CYC).
154 * Used for calibrating at MTC.
158 /* The adjusted last CTC value (from MTC).
160 * Used for calibrating at MTC.
164 /* The number of lost MTC updates since the last successful update. */
167 /* A flag saying whether we have seen a MTC packet. */
172 /* The amount by which the fcr value is right-shifted.
174 * Do not shift the value obtained by pt_tcal_fcr() when passing it to
175 * pt_time_update_cyc().
176 * Do shift the value passed to pt_tcal_set_fcr().
181 /* Initialize of reset timing calibration. */
182 extern void pt_tcal_init(struct pt_time_cal *tcal);
184 /* Query the estimated fast-counter:cycles ratio.
186 * Provides the estimated ratio in @fcr unless -pte_internal or
187 * -pte_no_time is returned.
189 * Returns zero on success, a negative error code otherwise.
190 * Returns -pte_internal if @fcr or @tcal is NULL.
191 * Returns -pte_no_time if no information is available.
193 extern int pt_tcal_fcr(uint64_t *fcr, const struct pt_time_cal *tcal);
195 /* Set the fast-counter:cycles ratio.
197 * Timing calibration takes one CBR or two MTC packets before it can provide
198 * first estimations. Use this to supply an initial value to be used in the
201 * Returns zero on success, a negative error code otherwise.
202 * Returns -pte_internal if @cal is NULL.
204 extern int pt_tcal_set_fcr(struct pt_time_cal *tcal, uint64_t fcr);
206 /* Update calibration based on an Intel PT packet.
208 * Returns zero on success, a negative error code otherwise.
210 extern int pt_tcal_update_tsc(struct pt_time_cal *,
211 const struct pt_packet_tsc *,
212 const struct pt_config *);
213 extern int pt_tcal_header_tsc(struct pt_time_cal *,
214 const struct pt_packet_tsc *,
215 const struct pt_config *);
216 extern int pt_tcal_update_cbr(struct pt_time_cal *,
217 const struct pt_packet_cbr *,
218 const struct pt_config *);
219 extern int pt_tcal_header_cbr(struct pt_time_cal *,
220 const struct pt_packet_cbr *,
221 const struct pt_config *);
222 extern int pt_tcal_update_tma(struct pt_time_cal *,
223 const struct pt_packet_tma *,
224 const struct pt_config *);
225 extern int pt_tcal_update_mtc(struct pt_time_cal *,
226 const struct pt_packet_mtc *,
227 const struct pt_config *);
228 extern int pt_tcal_update_cyc(struct pt_time_cal *,
229 const struct pt_packet_cyc *,
230 const struct pt_config *);
232 #endif /* PT_TIME_H */