1 /* 2 * Copyright (c) 2014-2018, Intel Corporation 3 * 4 * Redistribution and use in source and binary forms, with or without 5 * modification, are permitted provided that the following conditions are met: 6 * 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. 15 * 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. 27 */ 28 29 #ifndef PT_TIME_H 30 #define PT_TIME_H 31 32 #include <stdint.h> 33 34 struct pt_config; 35 struct pt_packet_tsc; 36 struct pt_packet_cbr; 37 struct pt_packet_tma; 38 struct pt_packet_mtc; 39 struct pt_packet_cyc; 40 41 42 /* Intel(R) Processor Trace timing. */ 43 struct pt_time { 44 /* The estimated Time Stamp Count. */ 45 uint64_t tsc; 46 47 /* The base Time Stamp Count (from TSC and MTC). */ 48 uint64_t base; 49 50 /* The estimated Fast Counter. */ 51 uint64_t fc; 52 53 /* The adjusted last CTC value (from MTC and TMA). */ 54 uint32_t ctc; 55 56 /* The adjusted CTC value when @fc was cleared (from MTC and TMA). */ 57 uint32_t ctc_cyc; 58 59 /* The number of lost MTC updates. */ 60 uint32_t lost_mtc; 61 62 /* The number of lost CYC updates. */ 63 uint32_t lost_cyc; 64 65 /* The core:bus ratio. */ 66 uint8_t cbr; 67 68 /* A flag saying whether we have seen a TSC packet. */ 69 uint32_t have_tsc:1; 70 71 /* A flag saying whether we have seen a CBR packet. */ 72 uint32_t have_cbr:1; 73 74 /* A flag saying whether we have seen a TMA packet. */ 75 uint32_t have_tma:1; 76 77 /* A flag saying whether we have seen a MTC packet. */ 78 uint32_t have_mtc:1; 79 }; 80 81 /* Initialize (or reset) the time. */ 82 extern void pt_time_init(struct pt_time *time); 83 84 /* Query the current time. 85 * 86 * Provides the estimated Time Stamp Count value in @tsc. 87 * 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. 90 * 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. 94 */ 95 extern int pt_time_query_tsc(uint64_t *tsc, uint32_t *lost_mtc, 96 uint32_t *lost_cyc, const struct pt_time *time); 97 98 /* Query the current core:bus ratio. 99 * 100 * Provides the core:bus ratio in @cbr. 101 * 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. 105 */ 106 extern int pt_time_query_cbr(uint32_t *cbr, const struct pt_time *time); 107 108 /* Update the time based on an Intel PT packet. 109 * 110 * Returns zero on success. 111 * Returns a negative error code, otherwise. 112 */ 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); 124 125 126 /* Timing calibration. 127 * 128 * Used for estimating the Fast-Counter:Cycles ratio. 129 * 130 * Ideally, we calibrate by counting CYCs between MTCs. Lacking MTCs, we 131 * use TSC, instead. 132 */ 133 struct pt_time_cal { 134 /* The estimated fast-counter:cycles ratio. */ 135 uint64_t fcr; 136 137 /* The minimal and maximal @fcr values. */ 138 uint64_t min_fcr, max_fcr; 139 140 /* The last TSC value. 141 * 142 * Used for calibrating at TSC. 143 */ 144 uint64_t tsc; 145 146 /* The number of cycles since the last TSC (from CYC). 147 * 148 * Used for calibrating at TSC. 149 */ 150 uint64_t cyc_tsc; 151 152 /* The number of cycles since the last MTC (from CYC). 153 * 154 * Used for calibrating at MTC. 155 */ 156 uint64_t cyc_mtc; 157 158 /* The adjusted last CTC value (from MTC). 159 * 160 * Used for calibrating at MTC. 161 */ 162 uint32_t ctc; 163 164 /* The number of lost MTC updates since the last successful update. */ 165 uint32_t lost_mtc; 166 167 /* A flag saying whether we have seen a MTC packet. */ 168 uint32_t have_mtc:1; 169 }; 170 171 enum { 172 /* The amount by which the fcr value is right-shifted. 173 * 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(). 177 */ 178 pt_tcal_fcr_shr = 8 179 }; 180 181 /* Initialize of reset timing calibration. */ 182 extern void pt_tcal_init(struct pt_time_cal *tcal); 183 184 /* Query the estimated fast-counter:cycles ratio. 185 * 186 * Provides the estimated ratio in @fcr unless -pte_internal or 187 * -pte_no_time is returned. 188 * 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. 192 */ 193 extern int pt_tcal_fcr(uint64_t *fcr, const struct pt_time_cal *tcal); 194 195 /* Set the fast-counter:cycles ratio. 196 * 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 199 * meantime. 200 * 201 * Returns zero on success, a negative error code otherwise. 202 * Returns -pte_internal if @cal is NULL. 203 */ 204 extern int pt_tcal_set_fcr(struct pt_time_cal *tcal, uint64_t fcr); 205 206 /* Update calibration based on an Intel PT packet. 207 * 208 * Returns zero on success, a negative error code otherwise. 209 */ 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 *); 231 232 #endif /* PT_TIME_H */ 233