summaryrefslogtreecommitdiff
path: root/doc/man/pt_qry_time.3.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/man/pt_qry_time.3.md')
-rw-r--r--doc/man/pt_qry_time.3.md128
1 files changed, 128 insertions, 0 deletions
diff --git a/doc/man/pt_qry_time.3.md b/doc/man/pt_qry_time.3.md
new file mode 100644
index 0000000000000..8bbfa4c8a5466
--- /dev/null
+++ b/doc/man/pt_qry_time.3.md
@@ -0,0 +1,128 @@
+% PT_QRY_TIME(3)
+
+<!---
+ ! Copyright (c) 2015-2018, Intel Corporation
+ !
+ ! Redistribution and use in source and binary forms, with or without
+ ! modification, are permitted provided that the following conditions are met:
+ !
+ ! * Redistributions of source code must retain the above copyright notice,
+ ! this list of conditions and the following disclaimer.
+ ! * Redistributions in binary form must reproduce the above copyright notice,
+ ! this list of conditions and the following disclaimer in the documentation
+ ! and/or other materials provided with the distribution.
+ ! * Neither the name of Intel Corporation nor the names of its contributors
+ ! may be used to endorse or promote products derived from this software
+ ! without specific prior written permission.
+ !
+ ! THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ ! AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ ! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ ! ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+ ! LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ ! CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ ! SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ ! INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ ! CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ ! ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ ! POSSIBILITY OF SUCH DAMAGE.
+ !-->
+
+# NAME
+
+pt_qry_time, pt_qry_core_bus_ratio, pt_insn_time, pt_insn_core_bus_ratio,
+pt_blk_time, pt_blk_core_bus_ratio - query an Intel(R) Processor Trace decoder
+for timing information
+
+
+# SYNOPSIS
+
+| **\#include `<intel-pt.h>`**
+|
+| **int pt_qry_time(struct pt_query_decoder \**decoder*, uint64_t \**time*,**
+| **uint32_t \**lost_mtc*, uint32_t \**lost_cyc*);**
+| **int pt_qry_core_bus_ratio(struct pt_query_decoder \**decoder*,**
+| **uint32_t \**cbr*);**
+|
+| **int pt_insn_time(struct pt_insn_decoder \**decoder*, uint64_t \**time*,**
+| **uint32_t \**lost_mtc*, uint32_t \**lost_cyc*);**
+| **int pt_insn_core_bus_ratio(struct pt_insn_decoder \**decoder*,**
+| **uint32_t \**cbr*);**
+|
+| **int pt_blk_time(struct pt_block_decoder \**decoder*, uint64_t \**time*,**
+| **uint32_t \**lost_mtc*, uint32_t \**lost_cyc*);**
+| **int pt_blk_core_bus_ratio(struct pt_block_decoder \**decoder*,**
+| **uint32_t \**cbr*);**
+
+Link with *-lipt*.
+
+
+# DESCRIPTION
+
+**pt_qry_time**(), **pt_insn_time**(), and **pt_blk_time**() provide the current
+estimated timestamp count (TSC) value in the unsigned integer variable pointed
+to by the *time* argument. The returned value corresponds to what an **rdtsc**
+instruction would have returned.
+
+At configurable intervals, Intel PT contains the full, accurate TSC value.
+Between those intervals, the timestamp count is estimated using a collection of
+lower-bandwidth packets, the Mini Time Counter (MTC) packet and the Cycle Count
+Packet (CYC). Depending on the Intel PT configuration, timing can be very
+precise at the cost of increased bandwidth or less precise but requiring lower
+bandwidth.
+
+The decoder needs to be calibrated in order to translate Cycle Counter ticks
+into Core Crystal Clock ticks. Without calibration, CYC packets need to be
+dropped. The decoder calibrates itself using MTC, CYC, and CBR packets.
+
+To interpret MTC and CYC packets, the decoder needs additional information
+provided in respective fields in the *pt_config* structure. Lacking this
+information, MTC packets may need to be dropped. This will impact the precision
+of the estimated timestamp count by losing periodic updates and it will impact
+calibration, which may result in reduced precision for cycle-accurate timing.
+
+The number of dropped MTC and CYC packets gives a rough idea about the quality
+of the estimated timestamp count. The value of dropped MTC and CYC packets is
+given in the unsigned integer variables pointed to by the *lost_mtc* and
+*lost_cyc* arguments respectively. If one or both of the arguments is NULL, no
+information on lost packets is provided for the respective packet type.
+
+**pt_qry_core_bus_ratio**(), **pt_insn_core_bus_ratio**(), and
+**pt_blk_core_bus_ratio**() give the last known core:bus ratio as provided by
+the Core Bus Ratio (CBR) Intel PT packet.
+
+
+# RETURN VALUE
+
+All functions return zero on success or a negative *pt_error_code* enumeration
+constant in case of an error.
+
+
+# ERRORS
+
+pte_invalid
+: The *decoder* or *time* (**pt_qry_time**(), **pt_insn_time**(), and
+ **pt_blk_time**()) or *cbr* (**pt_qry_core_bus_ratio**(),
+ **pt_insn_core_bus_ratio**(), and **pt_blk_core_bus_ratio**()) argument is
+ NULL.
+
+pte_no_time
+: There has not been a TSC packet to provide the full, accurate Time Stamp
+ Count. There may have been MTC or CYC packets, so the provided *time* may
+ be non-zero. It is zero if there has not been any timing packet yet.
+
+ Depending on the Intel PT configuration, TSC packets may not have been
+ enabled. In this case, the *time* value provides the relative time based on
+ other timing packets.
+
+pte_no_cbr
+: There has not been a CBR packet to provide the core:bus ratio. The *cbr*
+ value is undefined in this case.
+
+
+# SEE ALSO
+
+**pt_qry_alloc_decoder**(3), **pt_qry_free_decoder**(3),
+**pt_qry_cond_branch**(3), **pt_qry_indirect_branch**(3), **pt_qry_event**(3),
+**pt_insn_alloc_decoder**(3), **pt_insn_free_decoder**(3), **pt_insn_next**(3),
+**pt_blk_alloc_decoder**(3), **pt_blk_free_decoder**(3), **pt_blk_next**(3)