diff options
Diffstat (limited to 'doc/man')
33 files changed, 4397 insertions, 0 deletions
diff --git a/doc/man/CMakeLists.txt b/doc/man/CMakeLists.txt new file mode 100644 index 0000000000000..101581051959d --- /dev/null +++ b/doc/man/CMakeLists.txt @@ -0,0 +1,147 @@ +# Copyright (c) 2015-2019, 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. + +file(MAKE_DIRECTORY ${MAN_OUTPUT_DIRECTORY}/man3) + +find_program(PANDOC pandoc + DOC "Path to pandoc; used for building man pages." +) + +function(add_man_page filename section function) + set(input ${CMAKE_CURRENT_SOURCE_DIR}/${filename}) + set(output ${MAN_OUTPUT_DIRECTORY}/man${section}/${function}.${section}) + + add_custom_command( + OUTPUT ${output} + COMMAND ${PANDOC} -s -f markdown -t man -o ${output} ${input} + MAIN_DEPENDENCY ${filename} + ) +endfunction(add_man_page) + +function(install_man_page section function) + install( + FILES ${MAN_OUTPUT_DIRECTORY}/man${section}/${function}.${section} + DESTINATION ${CMAKE_INSTALL_MANDIR}/man${section} + ) +endfunction(install_man_page) + +function(add_man_page_alias section function alias) + set(output ${MAN_OUTPUT_DIRECTORY}/man${section}/${alias}.${section}) + + file(WRITE ${output} ".so man${section}/${function}.${section}\n") + + install_man_page(${section} ${alias}) +endfunction(add_man_page_alias) + +set(MAN3_FUNCTIONS + pt_library_version + pt_config + pt_packet + pt_alloc_encoder + pt_enc_get_offset + pt_enc_get_config + pt_pkt_alloc_decoder + pt_pkt_sync_forward + pt_pkt_get_offset + pt_qry_alloc_decoder + pt_qry_sync_forward + pt_qry_get_offset + pt_qry_cond_branch + pt_qry_event + pt_qry_time + pt_image_alloc + pt_image_add_file + pt_image_remove_by_filename + pt_image_set_callback + pt_insn_alloc_decoder + pt_insn_sync_forward + pt_insn_get_offset + pt_insn_get_image + pt_insn_next + pt_iscache_alloc + pt_iscache_add_file + pt_iscache_read + pt_iscache_set_limit + pt_blk_alloc_decoder + pt_blk_sync_forward + pt_blk_get_offset + pt_blk_next +) + +foreach (function ${MAN3_FUNCTIONS}) + set(MAN_PAGES ${MAN_PAGES} ${MAN_OUTPUT_DIRECTORY}/man3/${function}.3) + + add_man_page(${function}.3.md 3 ${function}) + install_man_page(3 ${function}) +endforeach () + +add_man_page_alias(3 pt_config pt_cpu_errata) +add_man_page_alias(3 pt_packet pt_enc_next) +add_man_page_alias(3 pt_packet pt_pkt_next) +add_man_page_alias(3 pt_alloc_encoder pt_free_encoder) +add_man_page_alias(3 pt_enc_get_offset pt_enc_sync_set) +add_man_page_alias(3 pt_enc_get_config pt_pkt_get_config) +add_man_page_alias(3 pt_enc_get_config pt_qry_get_config) +add_man_page_alias(3 pt_enc_get_config pt_insn_get_config) +add_man_page_alias(3 pt_enc_get_config pt_blk_get_config) +add_man_page_alias(3 pt_pkt_alloc_decoder pt_pkt_free_decoder) +add_man_page_alias(3 pt_pkt_sync_forward pt_pkt_sync_backward) +add_man_page_alias(3 pt_pkt_sync_forward pt_pkt_sync_set) +add_man_page_alias(3 pt_pkt_get_offset pt_pkt_get_sync_offset) +add_man_page_alias(3 pt_qry_alloc_decoder pt_qry_free_decoder) +add_man_page_alias(3 pt_qry_sync_forward pt_qry_sync_backward) +add_man_page_alias(3 pt_qry_sync_forward pt_qry_sync_set) +add_man_page_alias(3 pt_qry_get_offset pt_qry_get_sync_offset) +add_man_page_alias(3 pt_qry_cond_branch pt_qry_indirect_branch) +add_man_page_alias(3 pt_qry_time pt_qry_core_bus_ratio) +add_man_page_alias(3 pt_qry_time pt_insn_time) +add_man_page_alias(3 pt_qry_time pt_insn_core_bus_ratio) +add_man_page_alias(3 pt_qry_time pt_blk_time) +add_man_page_alias(3 pt_qry_time pt_blk_core_bus_ratio) +add_man_page_alias(3 pt_qry_event pt_insn_event) +add_man_page_alias(3 pt_qry_event pt_blk_event) +add_man_page_alias(3 pt_image_alloc pt_image_free) +add_man_page_alias(3 pt_image_alloc pt_image_name) +add_man_page_alias(3 pt_image_add_file pt_image_copy) +add_man_page_alias(3 pt_image_add_file pt_image_add_cached) +add_man_page_alias(3 pt_image_remove_by_filename pt_image_remove_by_asid) +add_man_page_alias(3 pt_insn_alloc_decoder pt_insn_free_decoder) +add_man_page_alias(3 pt_insn_sync_forward pt_insn_sync_backward) +add_man_page_alias(3 pt_insn_sync_forward pt_insn_sync_set) +add_man_page_alias(3 pt_insn_get_offset pt_insn_get_sync_offset) +add_man_page_alias(3 pt_insn_get_image pt_insn_set_image) +add_man_page_alias(3 pt_insn_get_image pt_blk_get_image) +add_man_page_alias(3 pt_insn_get_image pt_blk_set_image) +add_man_page_alias(3 pt_insn_next pt_insn) +add_man_page_alias(3 pt_iscache_alloc pt_iscache_free) +add_man_page_alias(3 pt_iscache_alloc pt_iscache_name) +add_man_page_alias(3 pt_blk_alloc_decoder pt_blk_free_decoder) +add_man_page_alias(3 pt_blk_sync_forward pt_blk_sync_backward) +add_man_page_alias(3 pt_blk_sync_forward pt_blk_sync_set) +add_man_page_alias(3 pt_blk_get_offset pt_blk_get_sync_offset) +add_man_page_alias(3 pt_blk_next pt_block) + +add_custom_target(man ALL DEPENDS ${MAN_PAGES}) diff --git a/doc/man/pt_alloc_encoder.3.md b/doc/man/pt_alloc_encoder.3.md new file mode 100644 index 0000000000000..f5e8e0ea5ae84 --- /dev/null +++ b/doc/man/pt_alloc_encoder.3.md @@ -0,0 +1,96 @@ +% PT_ALLOC_ENCODER(3) + +<!--- + ! Copyright (c) 2015-2019, 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_alloc_encoder, pt_free_encoder - allocate/free an Intel(R) Processor Trace +packet encoder + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **struct pt_packet_encoder \*** +| **pt_alloc_encoder(const struct pt_config \**config*);** +| +| **void pt_free_encoder(struct pt_packet_encoder \**encoder*);** + +Link with *-lipt*. + + +# DESCRIPTION + +**pt_alloc_encoder**() allocates a new Intel Processor Trace (Intel PT) packet +encoder and returns a pointer to it. The packet encoder generates Intel PT +trace from *pt_packet* objects. See **pt_enc_next**(3). + +The *config* argument points to a *pt_config* object. See **pt_config**(3). +The *config* argument will not be referenced by the returned encoder but the +trace buffer defined by the *config* argument's *begin* and *end* fields will. + +The returned packet encoder is initially synchronized onto the beginning of the +trace buffer specified in its *config* argument. Use **pt_enc_sync_set**(3) to +move it to any other position inside the trace buffer. + +**pt_free_encoder**() frees the Intel PT packet encoder pointed to by encoder*. +*The *encoder* argument must be NULL or point to an encoder that has been +*allocated by a call to **pt_alloc_encoder**(). + + +# RETURN VALUE + +**pt_alloc_encoder**() returns a pointer to a *pt_packet_encoder* object on +success or NULL in case of an error. + + +# EXAMPLE + +~~~{.c} +int foo(const struct pt_config *config) { + struct pt_packet_encoder *encoder; + errcode; + + encoder = pt_alloc_encoder(config); + if (!encoder) + return pte_nomem; + + errcode = bar(encoder); + + pt_free_encoder(encoder); + return errcode; +} +~~~ + + +# SEE ALSO + +**pt_config**(3), **pt_enc_sync_set**(3), **pt_enc_get_offset**(3), +**pt_enc_get_config**(3), **pt_enc_next**(3) diff --git a/doc/man/pt_blk_alloc_decoder.3.md b/doc/man/pt_blk_alloc_decoder.3.md new file mode 100644 index 0000000000000..aa6db3c536e65 --- /dev/null +++ b/doc/man/pt_blk_alloc_decoder.3.md @@ -0,0 +1,98 @@ +% PT_BLK_ALLOC_DECODER(3) + +<!--- + ! Copyright (c) 2016-2019, 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_blk_alloc_decoder, pt_blk_free_decoder - allocate/free an Intel(R) Processor +Trace block decoder + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **struct pt_block_decoder \*** +| **pt_blk_alloc_decoder(const struct pt_config \**config*);** +| +| **void pt_blk_free_decoder(struct pt_block_decoder \**decoder*);** + +Link with *-lipt*. + + +# DESCRIPTION + +A block decoder decodes raw Intel Processor Trace (Intel PT) into a sequence of +blocks of instructions described by the *pt_block* structure. See +**pt_blk_next**(3). + +**pt_blk_alloc_decoder**() allocates a new block decoder and returns a pointer +to it. The *config* argument points to a *pt_config* object. See +**pt_config**(3). The *config* argument will not be referenced by the returned +decoder but the trace buffer defined by the *config* argument's *begin* and +*end* fields will. + +The returned block decoder needs to be synchronized onto the trace stream before +it can be used. To synchronize the decoder, use **pt_blk_sync_forward**(3), +**pt_blk_sync_backward**(3), or **pt_blk_sync_set**(3). + +**pt_blk_free_decoder**() frees the Intel PT block decoder pointed to by +*decoder*. The *decoder* argument must be NULL or point to a decoder that has +been allocated by a call to **pt_blk_alloc_decoder**(). + + +# RETURN VALUE + +**pt_blk_alloc_decoder**() returns a pointer to a *pt_block_decoder* object on +success or NULL in case of an error. + + +# EXAMPLE + +~~~{.c} + struct pt_block_decoder *decoder; + int errcode; + + decoder = pt_blk_alloc_decoder(config); + if (!decoder) + return pte_nomem; + + errcode = decode(decoder); + + pt_blk_free_decoder(decoder); + return errcode; +~~~ + + +# SEE ALSO + +**pt_config**(3), **pt_blk_sync_forward**(3), **pt_blk_sync_backward**(3), +**pt_blk_sync_set**(3), **pt_blk_get_offset**(3), **pt_blk_get_sync_offset**(3), +**pt_blk_get_image**(3), **pt_blk_set_image**(3), **pt_blk_get_config**(3), +**pt_blk_time**(3), **pt_blk_core_bus_ratio**(3), **pt_blk_next**(3) diff --git a/doc/man/pt_blk_get_offset.3.md b/doc/man/pt_blk_get_offset.3.md new file mode 100644 index 0000000000000..da705c97fd31b --- /dev/null +++ b/doc/man/pt_blk_get_offset.3.md @@ -0,0 +1,82 @@ +% PT_BLK_GET_OFFSET(3) + +<!--- + ! Copyright (c) 2016-2019, 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_blk_get_offset, pt_blk_get_sync_offset - get an Intel(R) Processor Trace +block decoder's current/synchronization trace buffer offset + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **int pt_blk_get_offset(const struct pt_block_decoder \**decoder*,** +| **uint64_t \**offset*);** +| **int pt_blk_get_sync_offset(const struct pt_block_decoder \**decoder*,** +| **uint64_t \**offset*);** + +Link with *-lipt*. + + +# DESCRIPTION + +**pt_blk_get_offset**() provides *decoder*'s current position as offset in +bytes from the beginning of *decoder*'s trace buffer in the unsigned integer +variable pointed to by *offset*. + +**pt_blk_get_sync_offset**() provides *decoder*'s last synchronization point as +offset in bytes from the beginning of *decoder*'s trace buffer in the unsigned +integer variable pointed to by *offset*. + + +# RETURN VALUE + +Both functions return zero on success or a negative *pt_error_code* enumeration +constant in case of an error. + + +# ERRORS + +pte_invalid +: The *decoder* or *offset* argument is NULL. + +pte_nosync +: *decoder* has not been synchronized onto the trace stream. Use + **pt_blk_sync_forward**(3), **pt_blk_sync_backward**(3), or + **pt_blk_sync_set**(3) to synchronize *decoder*. + + +# SEE ALSO + +**pt_blk_alloc_decoder**(3), **pt_blk_free_decoder**(3), +**pt_blk_sync_forward**(3), **pt_blk_sync_backward**(3), +**pt_blk_sync_set**(3), **pt_blk_get_config**(3), **pt_blk_time**(3), +**pt_blk_core_bus_ratio**(3), **pt_blk_next**(3) diff --git a/doc/man/pt_blk_next.3.md b/doc/man/pt_blk_next.3.md new file mode 100644 index 0000000000000..ff576ef01d3ef --- /dev/null +++ b/doc/man/pt_blk_next.3.md @@ -0,0 +1,285 @@ +% PT_BLK_NEXT(3) + +<!--- + ! Copyright (c) 2016-2019, 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 NEXT 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_blk_next, pt_block - iterate over blocks of traced instructions + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **struct pt_block;** +| +| **int pt_blk_next(struct pt_blk_decoder \**decoder*,** +| **struct pt_blk \**blk*, size_t *size*);** +| +| **int pt_blk_next(struct pt_block_decoder \**decoder*,** +| **struct pt_block \**block*, size_t *size*);** + +Link with *-lipt*. + + +# DESCRIPTION + +**pt_blk_next**() provides the next block of instructions in execution order, +which is described by the *pt_block* structure. + +The *size* argument must be set to *sizeof(struct pt_block)*. The function will +provide at most *size* bytes of the *pt_block* structure. A newer decoder +library may truncate an extended *pt_block* object to *size* bytes. + +An older decoder library may provide less *pt_block* fields. Fields that are +not provided will be zero-initialized. For fields where zero is a valid value +(e.g. for bit-fields), check the decoder library version to determine which +fields are valid. See **pt_library_version**(3). + +On success, the next block of instructions is provided in the *pt_block* object +pointed to by the *block* argument. The *pt_block* structure is declared as: + +~~~{.c} +/** A block of instructions. + * + * Instructions in this block are executed sequentially but are not necessarily + * contiguous in memory. Users are expected to follow direct branches. + */ +struct pt_block { + /** The IP of the first instruction in this block. */ + uint64_t ip; + + /** The IP of the last instruction in this block. + * + * This can be used for error-detection. + */ + uint64_t end_ip; + + /** The image section that contains the instructions in this block. + * + * A value of zero means that the section did not have an identifier. + * The section was not added via an image section cache or the memory + * was read via the read memory callback. + */ + int isid; + + /** The execution mode for all instructions in this block. */ + enum pt_exec_mode mode; + + /** The instruction class for the last instruction in this block. + * + * This field may be set to ptic_error to indicate that the instruction + * class is not available. The block decoder may choose to not provide + * the instruction class in some cases for performance reasons. + */ + enum pt_insn_class iclass; + + /** The number of instructions in this block. */ + uint16_t ninsn; + + /** The raw bytes of the last instruction in this block in case the + * instruction does not fit entirely into this block's section. + * + * This field is only valid if \@truncated is set. + */ + uint8_t raw[pt_max_insn_size]; + + /** The size of the last instruction in this block in bytes. + * + * This field is only valid if \@truncated is set. + */ + uint8_t size; + + /** A collection of flags giving additional information about the + * instructions in this block. + * + * - all instructions in this block were executed speculatively. + */ + uint32_t speculative:1; + + /** - the last instruction in this block is truncated. + * + * It starts in this block's section but continues in one or more + * other sections depending on how fragmented the memory image is. + * + * The raw bytes for the last instruction are provided in \@raw and + * its size in \@size in this case. + */ + uint32_t truncated:1; +}; +~~~ + +The fields of the *pt_block* structure are described in more detail below: + +ip +: The virtual address of the first instruction in the block. The address + should be interpreted in the current address space context. + +end_ip +: The virtual address of the last instruction in the block. The address + should be interpreted in the current address space context. + + This can be used for error detection. Reconstruction of the instructions in + a block should end with the last instruction at *end_ip*. + +isid +: The image section identifier of the section from which the block of + instructions originated. This will be zero unless the instructions came + from a section that was added via an image section cache. See + **pt_image_add_cached**(3). + + The image section identifier can be used for reading the memory containing + an instruction in order to decode it and for tracing an instruction back to + its binary file and from there to source code. + +mode +: The execution mode at which the instructions in the block were executed. + The *pt_exec_mode* enumeration is declared as: + +~~~{.c} +/** An execution mode. */ +enum pt_exec_mode { + ptem_unknown, + ptem_16bit, + ptem_32bit, + ptem_64bit +}; +~~~ + +iclass +: A coarse classification of the last instruction in the block. This may be + *ptic_error* to indicate that the classification is not available. + + The block decoder knows the instruction class of the instruction that ended + the block most of the time. If it does, it provides this information to + save the caller the effort of decoding the instruction in some cases. + +ninsn +: The number of instructions contained in this block. + + The instructions are sequential in the sense that no trace is required for + reconstructing them. They are not necessarily contiguous in memory. + + The IP of the first instruction is given in the *ip* field and the IP of + other instructions can be determined by decoding and examining the previous + instruction. + +raw +: If the last instruction of this block can not be read entirely from this + block's section, this field provides the instruction's raw bytes. + + It is only valid if the *truncated* flag is set. + +size +: If the last instruction of this block can not be read entirely from this + block's section, this field provides the instruction's size in bytes. + + It is only valid if the *truncated* flag is set. + +speculative +: A flag giving the speculative execution status of all instructions in the + block. If set, the instructions were executed speculatively. Otherwise, + the instructions were executed normally. + +truncated +: A flag saying whether the last instruction in this block can not be read + entirely from this block's section. Some bytes need to be read from one or + more other sections. This can happen when an image section is partially + overwritten by another image section. + + If set, the last instruction's memory is provided in *raw* and its size in + *size*. + + +# RETURN VALUE + +**pt_blk_next**() returns zero or a positive value on success or a negative +*pt_error_code* enumeration constant in case of an error. + +On success, a bit-vector of *pt_status_flag* enumeration constants is returned. +The *pt_status_flag* enumeration is declared as: + +~~~{.c} +/** Decoder status flags. */ +enum pt_status_flag { + /** There is an event pending. */ + pts_event_pending = 1 << 0, + + /** The address has been suppressed. */ + pts_ip_suppressed = 1 << 1, + + /** There is no more trace data available. */ + pts_eos = 1 << 2 +}; +~~~ + +The *pts_event_pending* flag indicates that one or more events are pending. Use +**pt_blk_event**(3) to process pending events before calling **pt_blk_next**() +again. + +The *pt_eos* flag indicates that the information contained in the Intel PT +stream has been consumed. Further calls to **pt_blk_next**() will continue to +provide blocks for instructions as long as the instruction's addresses can be +determined without further trace. + + +# ERRORS + +pte_invalid +: The *decoder* or *block* argument is NULL or the *size* argument is too + small. + +pte_eos +: Decode reached the end of the trace stream. + +pte_nosync +: The decoder has not been synchronized onto the trace stream. Use + **pt_blk_sync_forward**(3), **pt_blk_sync_backward**(3), or + **pt_blk_sync_set**(3) to synchronize *decoder*. + +pte_bad_opc +: The decoder encountered an unsupported Intel PT packet opcode. + +pte_bad_packet +: The decoder encountered an unsupported Intel PT packet payload. + +pte_bad_query +: Execution flow reconstruction and trace got out of sync. + + This typically means that, on its way to the virtual address of the next + event, the decoder encountered a conditional or indirect branch for which it + did not find guidance in the trace. + + +# SEE ALSO + +**pt_blk_alloc_decoder**(3), **pt_blk_free_decoder**(3), +**pt_blk_sync_forward**(3), **pt_blk_sync_backward**(3), +**pt_blk_sync_set**(3), **pt_blk_time**(3), **pt_blk_core_bus_ratio**(3), +**pt_blk_event**(3) diff --git a/doc/man/pt_blk_sync_forward.3.md b/doc/man/pt_blk_sync_forward.3.md new file mode 100644 index 0000000000000..e5602f6545b95 --- /dev/null +++ b/doc/man/pt_blk_sync_forward.3.md @@ -0,0 +1,152 @@ +% PT_BLK_SYNC_FORWARD(3) + +<!--- + ! Copyright (c) 2016-2019, 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_blk_sync_forward, pt_blk_sync_backward, pt_blk_sync_set - synchronize an +Intel(R) Processor Trace block decoder + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **int pt_blk_sync_forward(struct pt_block_decoder \**decoder*);** +| **int pt_blk_sync_backward(struct pt_block_decoder \**decoder*);** +| **int pt_blk_sync_set(struct pt_block_decoder \**decoder*,** +| **uint64_t *offset*);** + +Link with *-lipt*. + + +# DESCRIPTION + +These functions synchronize an Intel Processor Trace (Intel PT) block decoder +pointed to by *decoder* onto the trace stream in *decoder*'s trace buffer. + +They search for a Packet Stream Boundary (PSB) packet in the trace stream and, +if successful, set *decoder*'s current position and synchronization position to +that packet and start processing packets. For synchronization to be +successfull, there must be a full PSB+ header in the trace stream. + +**pt_blk_sync_forward**() searches in forward direction from *decoder*'s +current position towards the end of the trace buffer. If *decoder* has been +newly allocated and has not been synchronized yet, the search starts from the +beginning of the trace. + +**pt_blk_sync_backward**() searches in backward direction from *decoder*'s +current position towards the beginning of the trace buffer. If *decoder* has +been newly allocated and has not been synchronized yet, the search starts from +the end of the trace. + +**pt_blk_sync_set**() searches at *offset* bytes from the beginning of its +trace buffer. + + +# RETURN VALUE + +All synchronization functions return zero or a positive value on success or a +negative *pt_error_code* enumeration constant in case of an error. + +On success, a bit-vector of *pt_status_flag* enumeration constants is returned. +The *pt_status_flag* enumeration is declared as: + +~~~{.c} +/** Decoder status flags. */ +enum pt_status_flag { + /** There is an event pending. */ + pts_event_pending = 1 << 0, + + /** The address has been suppressed. */ + pts_ip_suppressed = 1 << 1, + + /** There is no more trace data available. */ + pts_eos = 1 << 2 +}; +~~~ + +The *pts_event_pending* flag indicates that one or more events are pending. Use +**pt_blk_event**(3) to process pending events before calling **pt_blk_next**(3). + +The *pt_eos* flag indicates that the information contained in the Intel PT +stream has been consumed. Calls to **pt_blk_next**() will provide blocks for +instructions as long as the instruction's addresses can be determined without +further trace. + + +# ERRORS + +pte_invalid +: The *decoder* argument is NULL. + +pte_eos +: There is no (further) PSB+ header in the trace stream + (**pt_blk_sync_forward**() and **pt_blk_sync_backward**()) or at *offset* + bytes into the trace buffer (**pt_blk_sync_set**()). + +pte_nosync +: There is no PSB packet at *offset* bytes from the beginning of the trace + (**pt_blk_sync_set**() only). + +pte_bad_opc +: The decoder encountered an unsupported Intel PT packet opcode. + +pte_bad_packet +: The decoder encountered an unsupported Intel PT packet payload. + + +# EXAMPLE + +The following example re-synchronizes an Intel PT block decoder after decode +errors: + +~~~{.c} +int foo(struct pt_block_decoder *decoder) { + for (;;) { + int errcode; + + errcode = pt_blk_sync_forward(decoder); + if (errcode < 0) + return errcode; + + do { + errcode = decode(decoder); + } while (errcode >= 0); + } +} +~~~ + + +# SEE ALSO + +**pt_blk_alloc_decoder**(3), **pt_blk_free_decoder**(3), +**pt_blk_get_offset**(3), **pt_blk_get_sync_offset**(3), +**pt_blk_get_config**(3), **pt_blk_time**(3), **pt_blk_core_bus_ratio**(3), +**pt_blk_next**(3), **pt_blk_event**(3) diff --git a/doc/man/pt_config.3.md b/doc/man/pt_config.3.md new file mode 100644 index 0000000000000..94b1ca329833a --- /dev/null +++ b/doc/man/pt_config.3.md @@ -0,0 +1,359 @@ +% PT_CONFIG(3) + +<!--- + ! Copyright (c) 2015-2019, 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_config, pt_config_init, pt_cpu_errata - Intel(R) Processor Trace +encoder/decoder configuration + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **struct pt_config;** +| +| **void pt_config_init(struct pt_config \**config*);** +| +| **int pt_cpu_errata(struct pt_errata \**errata*, const struct pt_cpu \**cpu*);** + +Link with *-lipt*. + + +# DESCRIPTION + +The *pt_config* structure defines an Intel Processor Trace (Intel PT) encoder or +decoder configuration. It is required for allocating a trace packet encoder +(see **pt_alloc_encoder**(3)), a trace packet decoder (see +**pt_pkt_alloc_decoder**(3)), a query decoder (see **pt_qry_alloc_decoder**(3)), +or an instruction flow decoder (see **pt_insn_alloc_decoder**(3)). + +**pt_config_init**() zero-initializes its *config* argument and sets *config*'s +*size* field to *sizeof(struct pt_config)*. + +**pt_cpu_errata**() enables workarounds for known errata in its *errata* +argument for the processor defined by its family/model/stepping in its *cpu* +argument. + + +The *pt_config* structure is declared as: + +~~~{.c} +/** An Intel PT decoder configuration. */ +struct pt_config { + /** The size of the config structure in bytes. */ + size_t size; + + /** The trace buffer begin address. */ + uint8_t *begin; + + /** The trace buffer end address. */ + uint8_t *end; + + /** An optional callback for handling unknown packets. + * + * If \@callback is not NULL, it is called for any unknown + * opcode. + */ + struct { + /** The callback function. + * + * It shall decode the packet at \@pos into \@unknown. + * It shall return the number of bytes read upon success. + * It shall return a negative pt_error_code otherwise. + * The below context is passed as \@context. + */ + int (*callback)(struct pt_packet_unknown *unknown, + const struct pt_config *config, + const uint8_t *pos, void *context); + + /** The user-defined context for this configuration. */ + void *context; + } decode; + + /** The cpu on which Intel PT has been recorded. */ + struct pt_cpu cpu; + + /** The errata to apply when encoding or decoding Intel PT. */ + struct pt_errata errata; + + /** The CTC frequency. + * + * This is only required if MTC packets have been enabled in + * IA32_RTIT_CTRL.MTCEn. + */ + uint32_t cpuid_0x15_eax, cpuid_0x15_ebx; + + /** The MTC frequency as defined in IA32_RTIT_CTL.MTCFreq. + * + * This is only required if MTC packets have been enabled in + * IA32_RTIT_CTRL.MTCEn. + */ + uint8_t mtc_freq; + + /** The nominal frequency as defined in + * MSR_PLATFORM_INFO[15:8]. + * + * This is only required if CYC packets have been enabled in + * IA32_RTIT_CTRL.CYCEn. + * + * If zero, timing calibration will only be able to use MTC + * and CYC packets. + * + * If not zero, timing calibration will also be able to use + * CBR packets. + */ + uint8_t nom_freq; + + /** A collection of decoder-specific flags. */ + struct pt_conf_flags flags; + + /** The address filter configuration. */ + struct pt_conf_addr_filter addr_filter; +}; +~~~ + +The fields of the *pt_config* structure are described in more detail below: + +size +: The size of the *pt_config* structure for backward and forward + compatibility. Set it to *sizeof(struct pt_config)*. + +begin, end +: The begin and end of a user-allocated memory buffer; *begin* points to + the first byte of the buffer, *end* points to one past the last byte in the + buffer. + + The packet encoder will generate Intel PT packets into the memory buffer. + + The decoders expect the buffer to contain raw Intel PT packets. They decode + directly from the buffer and expect the buffer to remain valid until the + decoder has been freed. + +decode +: An optional packet decode callback function. If *decode.callback* is not + NULL, it will be called for any unknown packet with the decoder + configuration, the current decoder position and with a user-defined context + provided in *callback.context* as arguments. + + If the callback function is able to decode the packet, it shall return the + size of the decoded packet and provide details in a *pt_packet_unknown* + object. + + If the packet cannot be decoded, the callback function shall return a + negative *pt_error_code* enumeration constant. + + The *pt_packet_unknown* object can be used to provide user-defined + information back to the user when using the packet decoder to iterate over + Intel PT packets. Other decoders ignore this information but will skip + the packet if a non-zero size is returned by the callback function. + +cpu +: The processor on which the trace has been collected or for which the trace + should be generated. The processor is identified by its family, model, and + stepping. + +~~~{.c} +/** A cpu vendor. */ +enum pt_cpu_vendor { + pcv_unknown, + pcv_intel +}; + +/** A cpu identifier. */ +struct pt_cpu { + /** The cpu vendor. */ + enum pt_cpu_vendor vendor; + + /** The cpu family. */ + uint16_t family; + + /** The cpu model. */ + uint8_t model; + + /** The stepping. */ + uint8_t stepping; +}; +~~~ + +errata +: The errata workarounds to be applied by the trace encoder or decoder that + is created using this configuration. + + The *pt_errata* structure is a collection of one-bit-fields, one for each + supported erratum. Duplicate errata are indicated by comments for the + erratum for which the workaround was first implemented. Set the field of an + erratum to enable the correspondig workaround. + + The *pt_errata* structure is declared as: + +~~~{.c} +/** A collection of Intel PT errata. */ +struct pt_errata { + /** BDM70: Intel(R) Processor Trace PSB+ Packets May Contain + * Unexpected Packets. + * + * Same as: SKD024. + * + * Some Intel Processor Trace packets should be issued only + * between TIP.PGE and TIP.PGD packets. Due to this erratum, + * when a TIP.PGE packet is generated it may be preceded by a + * PSB+ that incorrectly includes FUP and MODE.Exec packets. + */ + uint32_t bdm70:1; + + /** BDM64: An Incorrect LBR or Intel(R) Processor Trace Packet + * May Be Recorded Following a Transactional Abort. + * + * Use of Intel(R) Transactional Synchronization Extensions + * (Intel(R) TSX) may result in a transactional abort. If an + * abort occurs immediately following a branch instruction, + * an incorrect branch target may be logged in an LBR (Last + * Branch Record) or in an Intel(R) Processor Trace (Intel(R) + * PT) packet before the LBR or Intel PT packet produced by + * the abort. + */ + uint32_t bdm64:1; + + [...] +}; +~~~ + +cpuid_0x15_eax, cpuid_0x15_ebx +: The values of *eax* and *ebx* on a *cpuid* call for leaf *0x15*. + + The value *ebx/eax* gives the ratio of the Core Crystal Clock (CTC) to + Timestamp Counter (TSC) frequency. + + This field is ignored by the packet encoder and packet decoder. It is + required for other decoders if Mini Time Counter (MTC) packets are enabled + in the collected trace. + +mtc_freq +: The Mini Time Counter (MTC) frequency as defined in *IA32_RTIT_CTL.MTCFreq*. + + This field is ignored by the packet encoder and packet decoder. It is + required for other decoders if Mini Time Counter (MTC) packets are enabled + in the collected trace. + +nom_freq +: The nominal or max non-turbo frequency. + + This field is ignored by the packet encoder and packet decoder. It is + used by other decoders if Cycle Count (CYC) packets are enabled to improve + timing calibration for cycle-accurate tracing. + + If the field is zero, the time tracking algorithm will use Mini Time + Counter (MTC) and Cycle Count (CYC) packets for calibration. + + If the field is non-zero, the time tracking algorithm will additionally be + able to calibrate at Core:Bus Ratio (CBR) packets. + +flags +: A collection of decoder-specific configuration flags. + +addr_filter +: The address filter configuration. It is declared as: + +~~~{.c} +/** The address filter configuration. */ +struct pt_conf_addr_filter { + /** The address filter configuration. + * + * This corresponds to the respective fields in IA32_RTIT_CTL MSR. + */ + union { + uint64_t addr_cfg; + + struct { + uint32_t addr0_cfg:4; + uint32_t addr1_cfg:4; + uint32_t addr2_cfg:4; + uint32_t addr3_cfg:4; + } ctl; + } config; + + /** The address ranges configuration. + * + * This corresponds to the IA32_RTIT_ADDRn_A/B MSRs. + */ + uint64_t addr0_a; + uint64_t addr0_b; + uint64_t addr1_a; + uint64_t addr1_b; + uint64_t addr2_a; + uint64_t addr2_b; + uint64_t addr3_a; + uint64_t addr3_b; + + /* Reserve some space. */ + uint64_t reserved[8]; +}; +~~~ + +# RETURN VALUE + +**pt_cpu_errata**() returns zero on success or a negative *pt_error_code* +enumeration constant otherwise. + + +# ERRORS + +**pt_cpu_errata**() may return the following errors: + +pte_invalid +: The *errata* or *cpu* argument is NULL. + + +# EXAMPLE + +~~~{.c} +int foo(uint8_t *trace_buffer, size_t size, struct pt_cpu cpu) { + struct pt_config config; + int errcode; + + pt_config_init(&config); + config.begin = trace_buffer; + config.end = trace_buffer + size; + config.cpu = cpu; + + errcode = pt_cpu_errata(&config.errata, &config.cpu); + if (errcode < 0) + return errcode; + + [...] +} +~~~ + + +# SEE ALSO + +**pt_alloc_encoder**(3), **pt_pkt_alloc_decoder**(3), +**pt_qry_alloc_decoder**(3), **pt_insn_alloc_decoder**(3) diff --git a/doc/man/pt_enc_get_config.3.md b/doc/man/pt_enc_get_config.3.md new file mode 100644 index 0000000000000..fcba6e397ba33 --- /dev/null +++ b/doc/man/pt_enc_get_config.3.md @@ -0,0 +1,77 @@ +% PT_ENC_GET_CONFIG(3) + +<!--- + ! Copyright (c) 2015-2019, 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_enc_get_config, pt_pkt_get_config, pt_qry_get_config, pt_insn_get_config, +pt_blk_get_config - get an Intel(R) Processor Trace encoder/decoder's +configuration + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **const struct pt_config \*** +| **pt_enc_get_config(const struct pt_encoder \**encoder*);** +| +| **const struct pt_config \*** +| **pt_pkt_get_config(const struct pt_packet_decoder \**decoder*);** +| +| **const struct pt_config \*** +| **pt_qry_get_config(const struct pt_query_decoder \**decoder*);** +| +| **const struct pt_config \*** +| **pt_insn_get_config(const struct pt_insn_decoder \**decoder*);** +| +| **const struct pt_config \*** +| **pt_blk_get_config(const struct pt_block_decoder \**decoder*);** + +Link with *-lipt*. + + +# DESCRIPTION + +These functions return a pointer to their argument's configuration. The +returned configuration object must not be freed. It is valid as long as their +argument is not freed. + + +# RETURN VALUE + +These functions returns a pointer to a *pt_config* object. The returned pointer +is NULL if their argument is NULL. + + +# SEE ALSO + +**pt_config**(3), **pt_alloc_encoder**(3), **pt_pkt_alloc_decoder**(3), +**pt_qry_alloc_decoder**(3), **pt_insn_alloc_decoder**(3), +**pt_blk_alloc_decoder**(3) diff --git a/doc/man/pt_enc_get_offset.3.md b/doc/man/pt_enc_get_offset.3.md new file mode 100644 index 0000000000000..528a5e1f451d1 --- /dev/null +++ b/doc/man/pt_enc_get_offset.3.md @@ -0,0 +1,77 @@ +% PT_ENC_GET_OFFSET(3) + +<!--- + ! Copyright (c) 2015-2019, 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_enc_get_offset, pt_enc_sync_set - get/set an Intel(R) Processor Trace packet +encoder's current trace buffer offset + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **int pt_enc_get_offset(const struct pt_packet_encoder \**encoder*,** +| **uint64_t \**offset*);** +| **int pt_enc_sync_set(const struct pt_packet_encoder \**encoder*,** +| **uint64_t *offset*);** + +Link with *-lipt*. + + +# DESCRIPTION + +**pt_enc_get_offset**() provides *encoder*'s current position as offset in bytes +from the beginning of *encoder*'s trace buffer in the unsigned integer variable +pointed to by *offset*. + +**pt_enc_sync_set**() sets *encoder*'s current position to *offset* bytes from +the beginning of its trace buffer. + + +# RETURN VALUE + +Both functions return zero on success or a negative *pt_error_code* enumeration +constant in case of an error. + + +# ERRORS + +pte_invalid +: The *encoder* or *offset* (for **pt_enc_sync_set**()) argument is NULL. + +pte_eos +: The *offset* argument is too big and the resulting position would be outside + of *encoder*'s trace buffer (**pt_enc_sync_set**() only). + + +# SEE ALSO + +**pt_enc_alloc_encoder**(3), **pt_enc_free_encoder**(3), **pt_enc_next**(3) diff --git a/doc/man/pt_image_add_file.3.md b/doc/man/pt_image_add_file.3.md new file mode 100644 index 0000000000000..9c644b632a760 --- /dev/null +++ b/doc/man/pt_image_add_file.3.md @@ -0,0 +1,135 @@ +% PT_IMAGE_ADD_FILE(3) + +<!--- + ! Copyright (c) 2015-2019, 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_image_add_file, pt_image_add_cached, pt_image_copy - add file sections to a +traced memory image descriptor + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **int pt_image_add_file(struct pt_image \**image*, const char \**filename*,** +| **uint64_t *offset*, uint64_t *size*,** +| **const struct pt_asid \**asid*, uint64_t *vaddr*);** +| **int pt_image_add_cached(struct pt_image \**image*,** +| **struct pt_image_section_cache \**iscache*,** +| **int *isid*, const struct pt_asid \**asid*);** +| **int pt_image_copy(struct pt_image \**image*,** +| **const struct pt_image \**src*);** + +Link with *-lipt*. + + +# DESCRIPTION + +**pt_image_add_file**() adds a new section to a *pt_image* object. The *image* +argument points to the *pt_image* object to which the new section is added. The +*filename* argument gives the absolute or relative path to the file on disk that +contains the section. The *offset* and *size* arguments define the section +within the file. The *size* argument is silently truncated to end the section +with the end of the underlying file. The *vaddr* argument gives the virtual +address at which the section is being loaded. + +**pt_image_add_cached**() adds a new section from an image section cache. See +**pt_iscache_add_file**(3). The *iscache* argument points to the +*pt_image_section_cache* object containing the section. The *isid* argument +gives the image section identifier for the desired section in that cache. + +The *asid* argument gives an optional address space identifier. If it is not +NULL, it points to a *pt_asid* structure, which is declared as: + +~~~{.c} +/** An Intel PT address space identifier. + * + * This identifies a particular address space when adding file + * sections or when reading memory. + */ +struct pt_asid { + /** The size of this object - set to sizeof(struct pt_asid). + */ + size_t size; + + /** The CR3 value. */ + uint64_t cr3; + + /** The VMCS Base address. */ + uint64_t vmcs; +}; +~~~ + +The *asid* argument can be used to prepare a collection of process, guest, and +hypervisor images to an Intel(R) Processor Trace (Intel PT) instruction flow +decoder. The decoder will select the current image based on CR3 and VMCS +information in the Intel PT trace. + +If only the CR3 or only the VMCS field should be considered by the decoder, +supply *pt_asid_no_cr3* and *pt_asid_no_vmcs* to the other field respectively. + +If the *asid* argument is NULL, the file section will be added for all +processes, guests, and hypervisor images. + +If the new section overlaps with an existing section, the existing section is +truncated or split to make room for the new section. + +**pt_image_copy**() adds file sections from the *pt_image* pointed to by the +*src* argument to the *pt_image* pointed to by the *dst* argument. + + +# RETURN VALUE + +**pt_image_add_file**() and **pt_image_add_cached**() return zero on success or +a negative *pt_error_code* enumeration constant in case of an error. + +**pt_image_copy**() returns the number of ignored sections on success or a +negative *pt_error_code* enumeration constant in case of an error. + + +# ERRORS + +pte_invalid +: The *image* or *filename* argument is NULL or the *offset* argument is too + big such that the section would start past the end of the file + (**pt_image_add_file**()). + The *image* or *iscache* argument is NULL (**pt_image_add_cached**()). + The *src* or *dst* argument is NULL (**pt_image_copy**()). + +pte_bad_image +: The *iscache* does not contain *isid* (**pt_image_add_cached**()). + + +# SEE ALSO + +**pt_image_alloc**(3), **pt_image_free**(3), +**pt_image_remove_by_filename**(3), **pt_image_remove_by_asid**(3), +**pt_image_set_callback**(3), **pt_insn_set_image**(3), +**pt_insn_get_image**(3), **pt_iscache_alloc**(3), **pt_iscache_add_file**(3) diff --git a/doc/man/pt_image_alloc.3.md b/doc/man/pt_image_alloc.3.md new file mode 100644 index 0000000000000..ba8b243d8f707 --- /dev/null +++ b/doc/man/pt_image_alloc.3.md @@ -0,0 +1,99 @@ +% PT_IMAGE_ALLOC(3) + +<!--- + ! Copyright (c) 2015-2019, 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_image_alloc, pt_image_free, pt_image_name - allocate/free a traced memory +image descriptor + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **struct pt_image \*pt_image_alloc(const char \**name*);** +| **const char \*pt_image_name(const struct pt_image \**image*);** +| **void pt_image_free(struct pt_image \**image*);** + +Link with *-lipt*. + + +# DESCRIPTION + +**pt_image_alloc**() allocates a new *pt_image* and returns a pointer to it. A +*pt_image* object defines the memory image that was traced as a collection of +file sections and the virtual addresses at which those sections were loaded. + +The *name* argument points to an optional zero-terminated name string. If the +*name* argument is NULL, it will be ignored and the returned *pt_image* object +will not have a name. Otherwise, the returned *pt_image* object will have a +copy of the string pointed to by the *name* argument as name. + +**pt_image_name**() returns the name of the *pt_image* object the *image* +argument points to. + +**pt_image_free**() frees the *pt_image* object pointed to by *image*. The +*image* argument must be NULL or point to an image that has been allocated by a +call to **pt_image_alloc**(). + + +# RETURN VALUE + +**pt_image_alloc**() returns a pointer to a *pt_image* object on success or NULL +in case of an error. + +**pt_image_name**() returns a pointer to a zero-terminated string of NULL if the +image does not have a name. + + +# EXAMPLE + +~~~{.c} +int foo(const char *name) { + struct pt_image *image; + errcode; + + image = pt_image_alloc(name); + if (!image) + return pte_nomem; + + errcode = bar(image); + + pt_image_free(image); + return errcode; +} +~~~ + + +# SEE ALSO + +**pt_image_add_file**(3), **pt_image_add_cached**(3), **pt_image_copy**(3), +**pt_image_remove_by_filename**(3), **pt_image_remove_by_asid**(3), +**pt_image_set_callback**(3), **pt_insn_set_image**(3), **pt_insn_get_image**(3) diff --git a/doc/man/pt_image_remove_by_filename.3.md b/doc/man/pt_image_remove_by_filename.3.md new file mode 100644 index 0000000000000..3561c5d831d8a --- /dev/null +++ b/doc/man/pt_image_remove_by_filename.3.md @@ -0,0 +1,150 @@ +% PT_IMAGE_REMOVE_BY_FILENAME(3) + +<!--- + ! Copyright (c) 2015-2019, 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_image_remove_by_filename, pt_image_remove_by_asid - remove sections from a +traced memory image descriptor + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **int pt_image_remove_by_filename(struct pt_image \**image*,** +| **const char \**filename*,** +| **const struct pt_asid \**asid*);** +| **int pt_image_remove_by_asid(struct pt_image \**image*,** +| **const struct pt_asid \**asid*);** + +Link with *-lipt*. + + +# DESCRIPTION + +**pt_image_remove_by_filename**() removes all sections from *image* that were +added by a call to **pt_image_add_file**(3) with an identical *filename* +argument or by a call to **pt_image_copy**(3) from such a section. Sections +that are based on the same underlying file but that were added using a different +*filename* argument are not removed. + +If the *asid* argument is not NULL, it removes only sections that were added +with a matching address-space identifier. See **pt_image_add_file**(3). + +**pt_image_remove_by_asid**(3) removes all sections from *image* that were added +by a call to **pt_image_add_file**(3) with a matching *asid* argument or by a +call to **pt_image_copy**(3) from such a section. See **pt_image_add_file**(3). + +Two *pt_asid* objects match in their "cr3* or *vmcs* field if one of them does +not provide the field (i.e. sets it to *pt_asid_no_cr3* or *pt_asid_no_vmcs* +respectively) or if the provided values are identical. Two *pt_asid* objects +match if they match in all fields. + + +# RETURN VALUE + +Both functions return the number of sections removed on success or a negative +*pt_error_code* enumeration constant in case of an error. + + +# ERRORS + +pte_invalid +: The *image* argument is NULL or the *filename* argument is NULL + (**pt_image_remove_by_filename**() only). + + +# EXAMPLE + +~~~{.c} +int foo(struct pt_image *image, uint64_t cr3) { + struct pt_asid asid1, asid2; + int errcode; + + pt_asid_init(&asid1); + asid1.cr3 = cr3; + + pt_asid_init(&asid2); + asid2.cr3 = ~cr3; + + errcode = pt_image_add_file(image, "/path/to/libfoo.so", + 0xa000, 0x100, &asid1, 0xb000); + if (errcode < 0) + return errcode; + + errcode = pt_image_add_file(image, "rel/path/to/libfoo.so", + 0xa000, 0x100, &asid1, 0xc000); + if (errcode < 0) + return errcode; + + /* This call would only remove the section added first: + * + * - filename matches only the first section's filename + * - NULL matches every asid + */ + (void) pt_image_remove_by_filename(image, + "/path/to/libfoo.so", + NULL); + + /* This call would not remove any of the above sections: + * + * - filename matches the first section's filename + * - asid2 does not match asid1 + */ + (void) pt_image_remove_by_filename(image, + "/path/to/libfoo.so", + &asid2); + + /* This call would not remove any of the above sections: + * + * - asid2 does not match asid1 + */ + (void) pt_image_remove_by_asid(image, &asid2); + + /* This call would remove both sections: + * + * - asid1 matches itself + */ + (void) pt_image_remove_by_asid(image, &asid1); + + /* This call would remove both sections: + * + * - NULL matches every asid + */ + (void) pt_image_remove_by_asid(image, NULL); +} +~~~ + + +# SEE ALSO + +**pt_image_alloc**(3), **pt_image_free**(3), **pt_image_add_file**(3), +**pt_image_add_cached**(3), **pt_image_copy**(3), **pt_insn_set_image**(3), +**pt_insn_get_image**(3) diff --git a/doc/man/pt_image_set_callback.3.md b/doc/man/pt_image_set_callback.3.md new file mode 100644 index 0000000000000..084979a29c620 --- /dev/null +++ b/doc/man/pt_image_set_callback.3.md @@ -0,0 +1,103 @@ +% PT_IMAGE_SET_CALLBACK(3) + +<!--- + ! Copyright (c) 2015-2019, 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_image_set_callback - set a traced memory image read memory callback + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **typedef int (read_memory_callback_t)(uint8_t \**buffer*, size_t *size*,** +| **const struct pt_asid \**asid*,** +| **uint64_t *ip*, void \**context*);** +| +| **int pt_image_set_callback(struct pt_image \**image*,** +| **read_memory_callback_t \**callback*,** +| **void \**context*);** + +Link with *-lipt*. + + +# DESCRIPTION + +**pt_image_set_callback**() sets the function pointed to by *callback* as the +read-memory callback function in the *pt_image* object pointed to by *image*. +Any previous read-memory callback function is replaced. The read-memory +callback function can be removed by passing NULL as *callback* argument. + +When the Intel(R) Processor Trace (Intel PT) instruction flow decoder that is +using *image* tries to read memory from a location that is not contained in any +of the file sections in *image*, it calls the read-memory callback function with +the following arguments: + +buffer +: A pre-allocated memory buffer to hold the to-be-read memory. The callback + function shall provide the read memory in that buffer. + +size +: The size of the memory buffer pointed to by the *buffer* argument. + +asid +: The address-space identifier specifying the process, guest, or hypervisor, + in which context the *ip* argument is to be interpreted. See + **pt_image_add_file**(3). + +ip +: The virtual address from which *size* bytes of memory shall be read. + +context +: The *context* argument passed to **pt_image_set_callback**(). + +The callback function shall return the number of bytes read on success (no more +than *size*) or a negative *pt_error_code* enumeration constant in case of an +error. + + +# RETURN VALUE + +**pt_image_set_callback**() returns zero on success or a negative +*pt_error_code* enumeration constant in case of an error. + + +# ERRORS + +pte_invalid +: If the *image* argument is NULL. + + +# SEE ALSO + +**pt_image_alloc**(3), **pt_image_free**(3), **pt_image_add_file**(3), +**pt_image_add_cached**(3), pt_image_copy**(3), +**pt_image_remove_by_filename**(3), pt_image_remove_by_asid**(3), +**pt_insn_set_image**(3), pt_insn_get_image**(3) diff --git a/doc/man/pt_insn_alloc_decoder.3.md b/doc/man/pt_insn_alloc_decoder.3.md new file mode 100644 index 0000000000000..c9a8efba5813d --- /dev/null +++ b/doc/man/pt_insn_alloc_decoder.3.md @@ -0,0 +1,101 @@ +% PT_INSN_ALLOC_DECODER(3) + +<!--- + ! Copyright (c) 2015-2019, 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_insn_alloc_decoder, pt_insn_free_decoder - allocate/free an Intel(R) +Processor Trace instruction flow decoder + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **struct pt_insn_decoder \*** +| **pt_insn_alloc_decoder(const struct pt_config \**config*);** +| +| **void pt_insn_free_decoder(struct pt_insn_decoder \**decoder*);** + +Link with *-lipt*. + + +# DESCRIPTION + +An instruction flow decoder decodes raw Intel Processor Trace (Intel PT) into a +sequence of instructions described by the *pt_insn* structure. See +**pt_insn_next**(3). + +**pt_insn_alloc_decoder**() allocates a new instruction flow decoder and returns +a pointer to it. The *config* argument points to a *pt_config* object. See +**pt_config**(3). The *config* argument will not be referenced by the returned +decoder but the trace buffer defined by the *config* argument's *begin* and +*end* fields will. + +The returned instruction flow decoder needs to be synchronized onto the trace +stream before it can be used. To synchronize the instruction flow decoder, use +**pt_insn_sync_forward**(3), **pt_insn_sync_backward**(3), or +**pt_insn_sync_set**(3). + +**pt_insn_free_decoder**() frees the Intel PT instruction flow decoder pointed +to by *decoder*. The *decoder* argument must be NULL or point to a decoder that +has been allocated by a call to **pt_insn_alloc_decoder**(). + + +# RETURN VALUE + +**pt_insn_alloc_decoder**() returns a pointer to a *pt_insn_decoder* object on +success or NULL in case of an error. + + +# EXAMPLE + +~~~{.c} +int foo(const struct pt_config *config) { + struct pt_insn_decoder *decoder; + errcode; + + decoder = pt_insn_alloc_decoder(config); + if (!decoder) + return pte_nomem; + + errcode = bar(decoder); + + pt_insn_free_decoder(decoder); + return errcode; +} +~~~ + + +# SEE ALSO + +**pt_config**(3), **pt_insn_sync_forward**(3), **pt_insn_sync_backward**(3), +**pt_insn_sync_set**(3), **pt_insn_get_offset**(3), **pt_insn_get_sync_offset**(3), +**pt_insn_get_image**(3), **pt_insn_set_image**(3), **pt_insn_get_config**(3), +**pt_insn_time**(3), **pt_insn_core_bus_ratio**(3), **pt_insn_next**(3) diff --git a/doc/man/pt_insn_get_image.3.md b/doc/man/pt_insn_get_image.3.md new file mode 100644 index 0000000000000..b5a503ea4d2b3 --- /dev/null +++ b/doc/man/pt_insn_get_image.3.md @@ -0,0 +1,93 @@ +% PT_INSN_GET_IMAGE(3) + +<!--- + ! Copyright (c) 2015-2019, 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_insn_get_image, pt_insn_set_image, pt_blk_get_image, pt_blk_set_image - +get/set an Intel(R) Processor Trace instruction flow or block decoder's traced +memory image descriptor + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **struct pt_image \*pt_insn_get_image(struct pt_insn_decoder \**decoder*);** +| **struct pt_image \*pt_blk_get_image(struct pt_block_decoder \**decoder*);** +| +| **int pt_insn_set_image(struct pt_insn_decoder \**decoder*,** +| **struct pt_image \**image*);** +| **int pt_blk_set_image(struct pt_block_decoder \**decoder*,** +| **struct pt_image \**image*);** + +Link with *-lipt*. + + +# DESCRIPTION + +**pt_insn_get_image**() and **pt_blk_get_image**() return the traced memory +*image descriptor that decoder* uses for reading instruction memory. See +***pt_image_alloc**(3). Every decoder comes with a default *pt_image* object +*that is initially empty and that will automatically be destroyed when the +*decoder is freed. + +**pt_insn_set_image**() and **pt_blk_set_image**() set the traced memory image +descriptor that *decoder* uses for reading instruction memory. If the *image* +argument is NULL, sets *decoder*'s image to be its default image. The user is +responsible for freeing the *pt_image* object that *image* points to when it is +no longer needed. + + +# RETURN VALUE + +**pt_insn_get_image**() and **pt_blk_get_image**() return a pointer to +*decoder*'s *pt_image* object. The returned pointer is NULL if the *decoder* +argument is NULL. + +**pt_insn_set_image**() and **pt_blk_set_image**() return zero on success or a +negative *pt_error_code* enumeration constant in case of an error. + + +# ERRORS + +pte_invalid +: The *decoder* argument is NULL. + + +# NOTES + +One *pt_image* object must not be shared between multiple decoders. Use +**pt_image_copy**(3) to copy a common image. + + +# SEE ALSO + +**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) diff --git a/doc/man/pt_insn_get_offset.3.md b/doc/man/pt_insn_get_offset.3.md new file mode 100644 index 0000000000000..31943f74fdf0d --- /dev/null +++ b/doc/man/pt_insn_get_offset.3.md @@ -0,0 +1,82 @@ +% PT_INSN_GET_OFFSET(3) + +<!--- + ! Copyright (c) 2015-2019, 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_insn_get_offset, pt_insn_get_sync_offset - get an Intel(R) Processor Trace +instruction flow decoder's current/synchronization trace buffer offset + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **int pt_insn_get_offset(const struct pt_insn_decoder \**decoder*,** +| **uint64_t \**offset*);** +| **int pt_insn_get_sync_offset(const struct pt_insn_decoder \**decoder*,** +| **uint64_t \**offset*);** + +Link with *-lipt*. + + +# DESCRIPTION + +**pt_insn_get_offset**() provides *decoder*'s current position as offset in +bytes from the beginning of *decoder*'s trace buffer in the unsigned integer +variable pointed to by *offset*. + +**pt_insn_get_sync_offset**() provides *decoder*'s last synchronization point as +offset in bytes from the beginning of *decoder*'s trace buffer in the unsigned +integer variable pointed to by *offset*. + + +# RETURN VALUE + +Both functions return zero on success or a negative *pt_error_code* enumeration +constant in case of an error. + + +# ERRORS + +pte_invalid +: The *decoder* or *offset* argument is NULL. + +pte_nosync +: *decoder* has not been synchronized onto the trace stream. Use + **pt_insn_sync_forward**(3), **pt_insn_sync_backward**(3), or + **pt_insn_sync_set**(3) to synchronize *decoder*. + + +# SEE ALSO + +**pt_insn_alloc_decoder**(3), **pt_insn_free_decoder**(3), +**pt_insn_sync_forward**(3), **pt_insn_sync_backward**(3), +**pt_insn_sync_set**(3), **pt_insn_get_config**(3), **pt_insn_time**(3), +**pt_insn_core_bus_ratio**(3), **pt_insn_next**(3) diff --git a/doc/man/pt_insn_next.3.md b/doc/man/pt_insn_next.3.md new file mode 100644 index 0000000000000..ec57df3f70125 --- /dev/null +++ b/doc/man/pt_insn_next.3.md @@ -0,0 +1,264 @@ +% PT_INSN_NEXT(3) + +<!--- + ! Copyright (c) 2015-2019, 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 NEXT 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_insn_next, pt_insn - iterate over traced instructions + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **struct pt_insn;** +| +| **int pt_insn_next(struct pt_insn_decoder \**decoder*,** +| **struct pt_insn \**insn*, size_t *size*);** + +Link with *-lipt*. + + +# DESCRIPTION + +**pt_insn_next**() provides the next instruction in execution order, which is +described by the *pt_insn* structure. + +The *size* argument must be set to *sizeof(struct pt_insn)*. The function will +provide at most *size* bytes of the *pt_insn* structure. A newer decoder +library may truncate an extended *pt_insn* object to *size* bytes. + +An older decoder library may provide less *pt_insn* fields. Fields that are not +provided will be zero-initialized. For fields where zero is a valid value +(e.g. for bit-fields), check the decoder library version to determine which +fields are valid. See **pt_library_version**(3). + +On success, the next instruction is provided in the *pt_insn* object pointed to +by the *insn* argument. The *pt_insn* structure is declared as: + +~~~{.c} +/** A single traced instruction. */ +struct pt_insn { + /** The virtual address in its process. */ + uint64_t ip; + + /** The image section identifier for the section containing this + * instruction. + * + * A value of zero means that the section did not have an identifier. + * The section was not added via an image section cache or the memory + * was read via the read memory callback. + */ + int isid; + + /** The execution mode. */ + enum pt_exec_mode mode; + + /** A coarse classification. */ + enum pt_insn_class iclass; + + /** The raw bytes. */ + uint8_t raw[pt_max_insn_size]; + + /** The size in bytes. */ + uint8_t size; + + /** A collection of flags giving additional information: + * + * - the instruction was executed speculatively. + */ + uint32_t speculative:1; + + /** - this instruction is truncated in its image section. + * + * It starts in the image section identified by \@isid and continues + * in one or more other sections. + */ + uint32_t truncated:1; +}; +~~~ + +The fields of the *pt_insn* structure are described in more detail below: + +ip +: The virtual address of the instruction. The address should be interpreted + in the current address space context. + +isid +: The image section identifier of the section from which the instruction + originated. This will be zero unless the instruction came from a section + that was added via an image section cache. See **pt_image_add_cached**(3). + + The image section identifier can be used to trace an instruction back to + its binary file and from there to source code. + +mode +: The execution mode at which the instruction was executed. The + *pt_exec_mode* enumeration is declared as: + +~~~{.c} +/** An execution mode. */ +enum pt_exec_mode { + ptem_unknown, + ptem_16bit, + ptem_32bit, + ptem_64bit +}; +~~~ + +iclass +: A coarse classification of the instruction suitable for constructing a call + back trace. The *pt_insn_class* enumeration is declared as: + +~~~{.c} +/** The instruction class. + * + * We provide only a very coarse classification suitable for + * reconstructing the execution flow. + */ +enum pt_insn_class { + /* The instruction could not be classified. */ + ptic_error, + + /* The instruction is something not listed below. */ + ptic_other, + + /* The instruction is a near (function) call. */ + ptic_call, + + /* The instruction is a near (function) return. */ + ptic_return, + + /* The instruction is a near unconditional jump. */ + ptic_jump, + + /* The instruction is a near conditional jump. */ + ptic_cond_jump, + + /* The instruction is a call-like far transfer. + * E.g. SYSCALL, SYSENTER, or FAR CALL. + */ + ptic_far_call, + + /* The instruction is a return-like far transfer. + * E.g. SYSRET, SYSEXIT, IRET, or FAR RET. + */ + ptic_far_return, + + /* The instruction is a jump-like far transfer. + * E.g. FAR JMP. + */ + ptic_far_jump +}; +~~~ + +raw +: The memory containing the instruction. + +size +: The size of the instruction in bytes. + +speculative +: A flag giving the speculative execution status of the instruction. If set, + the instruction was executed speculatively. Otherwise, the instruction was + executed normally. + +truncated +: A flag saying whether this instruction spans more than one image section. + If clear, this instruction originates from a single section identified by + *isid*. If set, the instruction overlaps two or more image sections. In + this case, *isid* identifies the section that contains the first byte. + + +# RETURN VALUE + +**pt_insn_next**() returns zero or a positive value on success or a negative +*pt_error_code* enumeration constant in case of an error. + +On success, a bit-vector of *pt_status_flag* enumeration constants is returned. +The *pt_status_flag* enumeration is declared as: + +~~~{.c} +/** Decoder status flags. */ +enum pt_status_flag { + /** There is an event pending. */ + pts_event_pending = 1 << 0, + + /** The address has been suppressed. */ + pts_ip_suppressed = 1 << 1, + + /** There is no more trace data available. */ + pts_eos = 1 << 2 +}; +~~~ + +The *pts_event_pending* flag indicates that one or more events are pending. Use +**pt_insn_event**(3) to process pending events before calling **pt_insn_next**() +again. + +The *pt_eos* flag indicates that the information contained in the Intel PT +stream has been consumed. Further calls to **pt_insn_next**() will continue to +provide instructions as long as the instruction's address can be determined +without further trace. + + +# ERRORS + +pte_invalid +: The *decoder* or *insn* argument is NULL or the *size* argument is too + small. + +pte_eos +: Decode reached the end of the trace stream. + +pte_nosync +: The decoder has not been synchronized onto the trace stream. Use + **pt_insn_sync_forward**(3), **pt_insn_sync_backward**(3), or + **pt_insn_sync_set**(3) to synchronize *decoder*. + +pte_bad_opc +: The decoder encountered an unsupported Intel PT packet opcode. + +pte_bad_packet +: The decoder encountered an unsupported Intel PT packet payload. + +pte_bad_query +: Execution flow reconstruction and trace got out of sync. + + This typically means that, on its way to the virtual address of the next + event, the decoder encountered a conditional or indirect branch for which it + did not find guidance in the trace. + + +# SEE ALSO + +**pt_insn_alloc_decoder**(3), **pt_insn_free_decoder**(3), +**pt_insn_sync_forward**(3), **pt_insn_sync_backward**(3), +**pt_insn_sync_set**(3), **pt_insn_time**(3), **pt_insn_core_bus_ratio**(3), +**pt_insn_event**(3) diff --git a/doc/man/pt_insn_sync_forward.3.md b/doc/man/pt_insn_sync_forward.3.md new file mode 100644 index 0000000000000..30fb338ac976c --- /dev/null +++ b/doc/man/pt_insn_sync_forward.3.md @@ -0,0 +1,153 @@ +% PT_INSN_SYNC_FORWARD(3) + +<!--- + ! Copyright (c) 2015-2019, 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_insn_sync_forward, pt_insn_sync_backward, pt_insn_sync_set - synchronize an +Intel(R) Processor Trace instruction flow decoder + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **int pt_insn_sync_forward(struct pt_insn_decoder \**decoder*);** +| **int pt_insn_sync_backward(struct pt_insn_decoder \**decoder*);** +| **int pt_insn_sync_set(struct pt_insn_decoder \**decoder*,** +| **uint64_t *offset*);** + +Link with *-lipt*. + + +# DESCRIPTION + +These functions synchronize an Intel Processor Trace (Intel PT) instruction flow +decoder pointed to by *decoder* onto the trace stream in *decoder*'s trace +buffer. + +They search for a Packet Stream Boundary (PSB) packet in the trace stream and, +if successful, set *decoder*'s current position and synchronization position to +that packet and start processing packets. For synchronization to be +successfull, there must be a full PSB+ header in the trace stream. + +**pt_insn_sync_forward**() searches in forward direction from *decoder*'s +current position towards the end of the trace buffer. If *decoder* has been +newly allocated and has not been synchronized yet, the search starts from the +beginning of the trace. + +**pt_insn_sync_backward**() searches in backward direction from *decoder*'s +current position towards the beginning of the trace buffer. If *decoder* has +been newly allocated and has not been synchronized yet, the search starts from +the end of the trace. + +**pt_insn_sync_set**() searches at *offset* bytes from the beginning of its +trace buffer. + + +# RETURN VALUE + +All synchronization functions return zero or a positive value on success or a +negative *pt_error_code* enumeration constant in case of an error. + +On success, a bit-vector of *pt_status_flag* enumeration constants is returned. +The *pt_status_flag* enumeration is declared as: + +~~~{.c} +/** Decoder status flags. */ +enum pt_status_flag { + /** There is an event pending. */ + pts_event_pending = 1 << 0, + + /** The address has been suppressed. */ + pts_ip_suppressed = 1 << 1, + + /** There is no more trace data available. */ + pts_eos = 1 << 2 +}; +~~~ + +The *pts_event_pending* flag indicates that one or more events are pending. Use +**pt_insn_event**(3) to process pending events before calling +**pt_insn_next**(3). + +The *pt_eos* flag indicates that the information contained in the Intel PT +stream has been consumed. Calls to **pt_insn_next**() will provide instructions +as long as the instruction's address can be determined without trace. + + +# ERRORS + +pte_invalid +: The *decoder* argument is NULL. + +pte_eos +: There is no (further) PSB+ header in the trace stream + (**pt_insn_sync_forward**() and **pt_insn_sync_backward**()) or at *offset* + bytes into the trace buffer (**pt_insn_sync_set**()). + +pte_nosync +: There is no PSB packet at *offset* bytes from the beginning of the trace + (**pt_insn_sync_set**() only). + +pte_bad_opc +: The decoder encountered an unsupported Intel PT packet opcode. + +pte_bad_packet +: The decoder encountered an unsupported Intel PT packet payload. + + +# EXAMPLE + +The following example re-synchronizes an Intel PT instruction flow decoder after +decode errors: + +~~~{.c} +int foo(struct pt_insn_decoder *decoder) { + for (;;) { + int status; + + status = pt_insn_sync_forward(decoder); + if (status < 0) + return status; + + do { + status = decode(decoder, status); + } while (status >= 0); + } +} +~~~ + + +# SEE ALSO + +**pt_insn_alloc_decoder**(3), **pt_insn_free_decoder**(3), +**pt_insn_get_offset**(3), **pt_insn_get_sync_offset**(3), +**pt_insn_get_config**(3), **pt_insn_time**(3), **pt_insn_core_bus_ratio**(3), +**pt_insn_next**(3), **pt_insn_event**(3) diff --git a/doc/man/pt_iscache_add_file.3.md b/doc/man/pt_iscache_add_file.3.md new file mode 100644 index 0000000000000..cf959299182e3 --- /dev/null +++ b/doc/man/pt_iscache_add_file.3.md @@ -0,0 +1,98 @@ +% PT_ISCACHE_ADD_FILE(3) + +<!--- + ! Copyright (c) 2015-2019, 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_iscache_add_file - add file sections to a traced memory image section cache + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **int pt_iscache_add_file(struct pt_image_section_cache \**iscache*,** +| **const char \**filename*, uint64_t *offset*,** +| **uint64_t *size*, uint64_t *vaddr*);** + +Link with *-lipt*. + + +# DESCRIPTION + +**pt_iscache_add_file**() adds a new section consisting of *size* bytes starting +at *offset* in *filename* loaded at *vaddr* to *iscache*. + +On success, **pt_iscache_add_file**() returns a positive integer identifier that +uniquely identifies the added section in that cache. This identifier can be +used to add sections from an image section cache to one or more traced memory +images. See **pt_image_add_cached**(3). Sections added from an image section +cache will be shared across images. It can also be used to read memory from the +cached section. See **pt_iscache_read**(3). + +If the cache already contains a suitable section, no section is added and the +identifier for the existing section is returned. If the cache already contains +a section that only differs in the load address, a new section is added that +shares the underlying file section. + + +# RETURN VALUE + +**pt_iscache_add_file**() returns a positive image section identifier on success +or a negative *pt_error_code* enumeration constant in case of an error. + + +# ERRORS + +pte_invalid +: The *iscache* or *filename* argument is NULL or the *offset* argument is too + big such that the section would start past the end of the file. + + +# EXAMPLE + +~~~{.c} +int add_file(struct pt_image_section_cache *iscache, struct pt_image *image, + const char *filename, uint64_t offset, uint64_t size, + uint64_t vaddr, const struct pt_asid *asid) { + int isid; + + isid = pt_iscache_add_file(iscache, filename, offset, size, vaddr); + if (isid < 0) + return isid; + + return pt_image_add_cached(image, iscache, isid, asid); +} +~~~ + + +# SEE ALSO + +**pt_iscache_alloc**(3), **pt_iscache_free**(3), **pt_iscache_read**(3), +**pt_image_add_cached**(3) diff --git a/doc/man/pt_iscache_alloc.3.md b/doc/man/pt_iscache_alloc.3.md new file mode 100644 index 0000000000000..47f9edfe453ca --- /dev/null +++ b/doc/man/pt_iscache_alloc.3.md @@ -0,0 +1,102 @@ +% PT_ISCACHE_ALLOC(3) + +<!--- + ! Copyright (c) 2015-2019, 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_iscache_alloc, pt_iscache_free, pt_iscache_name - allocate/free a traced memory +image section cache + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **struct pt_image_section_cache \*pt_iscache_alloc(const char \**name*);** +| **const char \*pt_iscache_name(const struct pt_image_section_cache \**iscache*);** +| **void pt_iscache_free(struct pt_image_section_cache \**iscache*);** + +Link with *-lipt*. + + +# DESCRIPTION + +**pt_iscache_alloc**() allocates a new *pt_image_section_cache* and returns a +pointer to it. A *pt_image_section_cache* object contains a collection of file +sections and the virtual addresses at which those sections were loaded. + +The image sections can be added to one or more *pt_image* objects. The +underlying file sections will be mapped once and their content will be shared +across images. + +The *name* argument points to an optional zero-terminated name string. If the +*name* argument is NULL, it will be ignored and the returned +*pt_image_section_cache* object will not have a name. Otherwise, the returned +*pt_image_section_object* object will have a copy of the string pointed to by +the *name* argument as name. + +**pt_iscache_name**() returns the name of the *pt_image_section_cache* object +the *iscache* argument points to. + +**pt_iscache_free**() frees the *pt_image_section_cache* object pointed to by +*iscache*. The *iscache* argument must be NULL or point to an image section +cache that has been allocated by a call to **pt_iscache_alloc**(). + + +# RETURN VALUE + +**pt_iscache_alloc**() returns a pointer to a *pt_image_section_cache* object +on success or NULL in case of an error. + +**pt_iscache_name**() returns a pointer to a zero-terminated string of NULL if the +image section cache does not have a name. + + +# EXAMPLE + +~~~{.c} +int foo(const char *name) { + struct pt_image_section_cache *iscache; + errcode; + + image = pt_iscache_alloc(name); + if (!iscache) + return pte_nomem; + + errcode = bar(iscache); + + pt_iscache_free(iscache); + return errcode; +} +~~~ + + +# SEE ALSO + +**pt_iscache_add_file**(3), **pt_image_add_cached**(3) diff --git a/doc/man/pt_iscache_read.3.md b/doc/man/pt_iscache_read.3.md new file mode 100644 index 0000000000000..0e16b33d6050d --- /dev/null +++ b/doc/man/pt_iscache_read.3.md @@ -0,0 +1,89 @@ +% PT_ISCACHE_READ(3) + +<!--- + ! Copyright (c) 2015-2019, 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_iscache_read - read memory from a cached file section + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **int pt_iscache_read(struct pt_image_section_cache \**iscache*,** +| **uint8_t \**buffer*, uint64_t *size*, int *isid*,** +| **uint64_t *vaddr*);** + +Link with *-lipt*. + + +# DESCRIPTION + +**pt_iscache_read**() reads memory from a cached file section. The file section +must have previously been added by a call to **pt_iscache_add**(3). The +*iscache* argument points to the *pt_image_section_cache* object. It must be +the same that was used in the corresponding **pt_iscache_add**(3) call. The +*buffer* argument must point to a memory buffer of at least *size* bytes. The +*isid* argument identifies the file section from which memory is read. It must +be the same identifier that was returned from the corresponding +**pt_iscache_add**(3) call that added the file section to the cache. The *vaddr* +argument gives the virtual address from which *size* bytes of memory shall be +read. + +On success, **pt_iscache_read**() copies at most *size* bytes of memory from the +cached file section identified by *isid* in *iscache* starting at virtual +address *vaddr* into *buffer* and returns the number of bytes that were copied. + +Multiple calls to **pt_iscache_read**() may be necessary if *size* is bigger +than 4Kbyte or if the read crosses a section boundary. + + +# RETURN VALUE + +**pt_iscache_read**() returns the number of bytes that were read on success +or a negative *pt_error_code* enumeration constant in case of an error. + + +# ERRORS + +pte_invalid +: The *iscache* or *buffer* argument is NULL or the *size* argument is zero. + +pte_bad_image +: The *iscache* does not contain a section identified by *isid*. + +pte_nomap +: The *vaddr* argument lies outside of the virtual address range of the cached + section. + + +# SEE ALSO + +**pt_iscache_alloc**(3), **pt_iscache_free**(3), **pt_iscache_add**(3) diff --git a/doc/man/pt_iscache_set_limit.3.md b/doc/man/pt_iscache_set_limit.3.md new file mode 100644 index 0000000000000..c87eb942a6fa7 --- /dev/null +++ b/doc/man/pt_iscache_set_limit.3.md @@ -0,0 +1,73 @@ +% PT_ISCACHE_SET_LIMIT(3) + +<!--- + ! Copyright (c) 2017-2019, 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_iscache_set_limit - set the mapped image section cache limit + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **int pt_iscache_set_limit(struct pt_image_section_cache \**iscache*,** +| **uint64_t *limit*);** + +Link with *-lipt*. + + +# DESCRIPTION + +**pt_iscache_set_limit**() sets the mapped image section cache limit. The +*iscache* argument points to the *pt_image_section_cache* object. The *limit* +argument gives the limit in bytes. + +The image section cache will spend at most *limit* bytes to keep image sections +mapped as opposed to mapping and unmapping them when reading from them. This +includes the memory for any caches associated with the mapped section. + +A *limit* of zero disables caching and clears the cache. + + +# RETURN VALUE + +**pt_iscache_set_limit**() returns zero on success or a negative *pt_error_code* +enumeration constant in case of an error. + + +# ERRORS + +pte_invalid +: The *iscache* argument is NULL. + + +# SEE ALSO + +**pt_iscache_alloc**(3), **pt_iscache_free**(3), **pt_iscache_read**(3) diff --git a/doc/man/pt_library_version.3.md b/doc/man/pt_library_version.3.md new file mode 100644 index 0000000000000..daeaf0b3e086e --- /dev/null +++ b/doc/man/pt_library_version.3.md @@ -0,0 +1,72 @@ +% PT_LIBRARY_VERSION(3) + +<!--- + ! Copyright (c) 2015-2019, 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_library_version - version information + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **struct pt_version pt_library_version();** + +Link with *-lipt*. + + +# DESCRIPTION + +**pt_library_version**() returns the decoder library version. + + +# RETURN VALUE + +**pt_library_version**() returns a *pt_version* structure which is declared as: + +~~~{.c} +/** The library version. */ +struct pt_version { + /** Major version number. */ + uint8_t major; + + /** Minor version number. */ + uint8_t minor; + + /** Patch level. */ + uint16_t patch; + + /** Build number. */ + uint32_t build; + + /** Version extension. */ + const char *ext; +}; +~~~ diff --git a/doc/man/pt_packet.3.md b/doc/man/pt_packet.3.md new file mode 100644 index 0000000000000..c8d1c806da1b4 --- /dev/null +++ b/doc/man/pt_packet.3.md @@ -0,0 +1,197 @@ +% PT_PACKET(3) + +<!--- + ! Copyright (c) 2015-2019, 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_packet, pt_enc_next, pt_pkt_next - encode/decode an Intel(R) Processor Trace +packet + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **struct pt_packet;** +| +| **int pt_enc_next(struct pt_packet_encoder \**encoder*,** +| **const struct pt_packet \**packet*);** +| +| **int pt_pkt_next(struct pt_packet_decoder \**decoder*,** +| **struct pt_packet \**packet*, size_t *size*);** + +Link with *-lipt*. + + +# DESCRIPTION + +**pt_enc_next**() encodes its *packet* argument as Intel Processor Trace (Intel +PT) packet at *encoder*'s current position. On success, sets *encoder*'s +current position to point to the first byte after the encoded packet. + + +**pt_pkt_next**() decodes the Intel PT packet at decoder*'s current position +into *packet*. On success, sets *decoder*'s current position to point to the +first byte after the decoded packet. + +The caller is responsible for allocating and freeing the *pt_packet* object +pointed to be the *packet* argument. + +The *size* argument of **pt_pkt_next**() must be set to *sizeof(struct +pt_packet)*. The function will provide at most *size* bytes of packet data. A +newer decoder library may provide packet types that are not yet defined. Those +packets may be truncated. Unknown packet types should be ignored. + +If the packet decoder does not know the packet opcode at *decoder*'s current +position and if *decoder*'s configuration contains a packet decode callback +function, **pt_pkt_next**() will call that callback function to decode the +unknown packet. On success, a *ppt_unknown* packet type is provided with the +information provided by the decode callback function. + +An Intel PT packet is described by the *pt_packet* structure, which is declared +as: + +~~~{.c} +/** An Intel PT packet. */ +struct pt_packet { + /** The type of the packet. + * + * This also determines the \@variant field. + */ + enum pt_packet_type type; + + /** The size of the packet including opcode and payload. */ + uint8_t size; + + /** Packet specific data. */ + union { + /** Packets: pad, ovf, psb, psbend, stop - no payload. */ + + /** Packet: tnt-8, tnt-64. */ + struct pt_packet_tnt tnt; + + /** Packet: tip, fup, tip.pge, tip.pgd. */ + struct pt_packet_ip ip; + + /** Packet: mode. */ + struct pt_packet_mode mode; + + /** Packet: pip. */ + struct pt_packet_pip pip; + + /** Packet: tsc. */ + struct pt_packet_tsc tsc; + + /** Packet: cbr. */ + struct pt_packet_cbr cbr; + + /** Packet: tma. */ + struct pt_packet_tma tma; + + /** Packet: mtc. */ + struct pt_packet_mtc mtc; + + /** Packet: cyc. */ + struct pt_packet_cyc cyc; + + /** Packet: vmcs. */ + struct pt_packet_vmcs vmcs; + + /** Packet: mnt. */ + struct pt_packet_mnt mnt; + + /** Packet: unknown. */ + struct pt_packet_unknown unknown; + } payload; +}; +~~~ + +See the *intel-pt.h* header file for more detail. + + +# RETURN VALUE + +**pt_enc_next**() returns the number of bytes written on success or a negative +*pt_error_code* enumeration constant in case of an error. + +**pt_pkt_next**() returns the number of bytes consumed on success or a negative +*pt_error_code* enumeration constant in case of an error. + + +# ERRORS + +pte_invalid +: The *encoder*/*decoder* or *packet* argument is NULL or the *size* argument + is zero (**pt_pkt_next**() only). + +pte_nosync +: *decoder* has not been synchronized onto the trace stream (**pt_pkt_next**() + only). Use **pt_pkt_sync_forward**(3), **pt_pkt_sync_backward**(3), or + **pt_pkt_sync_set**(3) to synchronize *decoder*. + +pte_eos +: Encode/decode has reached the end of the trace buffer. There is not enough + space in the trace buffer to generate *packet* (**pt_enc_next**()) or the + trace buffer does not contain a full Intel PT packet (**pt_pkt_next**()). + +pte_bad_opc +: The type of the *packet* argument is not supported (**pt_enc_next**()) or + the packet at *decoder*'s current position is not supported + (**pt_pkt_next**()). + +pte_bad_packet +: The payload or parts of the payload of the *packet* argument is not + supported (**pt_enc_next**()) or the packet at *decoder*'s current position + contains unsupported payload (**pt_pkt_next**()). + + +# EXAMPLE + +The example shows a typical Intel PT packet decode loop. + +~~~{.c} +int foo(struct pt_packet_decoder *decoder) { + for (;;) { + struct pt_packet packet; + int errcode; + + errcode = pt_pkt_next(decoder, &packet, sizeof(packet)); + if (errcode < 0) + return errcode; + + [...] + } +} +~~~ + + +# SEE ALSO + +**pt_alloc_encoder**(3), **pt_pkt_alloc_decoder**(3), +**pt_pkt_sync_forward**(3), **pt_pkt_sync_backward**(3), **pt_pkt_sync_set**(3) diff --git a/doc/man/pt_pkt_alloc_decoder.3.md b/doc/man/pt_pkt_alloc_decoder.3.md new file mode 100644 index 0000000000000..f7bc28a835bd0 --- /dev/null +++ b/doc/man/pt_pkt_alloc_decoder.3.md @@ -0,0 +1,98 @@ +% PT_PKT_ALLOC_DECODER(3) + +<!--- + ! Copyright (c) 2015-2019, 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_pkt_alloc_decoder, pt_pkt_free_decoder - allocate/free an Intel(R) Processor +Trace packet decoder + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **struct pt_packet_decoder \*** +| **pt_pkt_alloc_decoder(const struct pt_config \**config*);** +| +| **void pt_pkt_free_decoder(struct pt_packet_decoder \**decoder*);** + +Link with *-lipt*. + + +# DESCRIPTION + +**pt_pkt_alloc_decoder**() allocates a new Intel Processor Trace (Intel PT) +packet decoder and returns a pointer to it. The packet decoder decodes raw +Intel PT trace into a stream of *pt_packet* objects. See **pt_pkt_next**(3). + +The *config* argument points to a *pt_config* object. See **pt_config**(3). +The *config* argument will not be referenced by the returned decoder but the +trace buffer defined by the *config* argument's *begin* and *end* fields will. + +The returned packet decoder needs to be synchronized onto the trace stream +before it can be used. To synchronize the packet decoder, use +**pt_pkt_sync_forward**(3), **pt_pkt_sync_backward**(3), or +**pt_pkt_sync_set**(3). + +**pt_pkt_free_decoder**() frees the Intel PT packet decoder pointed to by +*decoder*. The *decoder* argument must be NULL or point to a decoder that has +been allocated by a call to **pt_pkt_alloc_decoder**(). + + +# RETURN VALUE + +**pt_pkt_alloc_decoder**() returns a pointer to a *pt_packet_decoder* object on +success or NULL in case of an error. + + +# EXAMPLE + +~~~{.c} +int foo(const struct pt_config *config) { + struct pt_packet_decoder *decoder; + errcode; + + decoder = pt_pkt_alloc_decoder(config); + if (!decoder) + return pte_nomem; + + errcode = bar(decoder); + + pt_pkt_free_decoder(decoder); + return errcode; +} +~~~ + + +# SEE ALSO + +**pt_config**(3), **pt_pkt_sync_forward**(3), **pt_pkt_sync_backward**(3), +**pt_pkt_sync_set**(3), **pt_pkt_get_offset**(3), **pt_pkt_get_sync_offset**(3), +**pt_pkt_get_config**(3), **pt_pkt_next**(3) diff --git a/doc/man/pt_pkt_get_offset.3.md b/doc/man/pt_pkt_get_offset.3.md new file mode 100644 index 0000000000000..fb723d236f598 --- /dev/null +++ b/doc/man/pt_pkt_get_offset.3.md @@ -0,0 +1,81 @@ +% PT_PKT_GET_OFFSET(3) + +<!--- + ! Copyright (c) 2015-2019, 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_pkt_get_offset, pt_pkt_get_sync_offset - get an Intel(R) Processor Trace +packet decoder's current/synchronization trace buffer offset + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **int pt_pkt_get_offset(const struct pt_packet_decoder \**decoder*,** +| **uint64_t \**offset*);** +| **int pt_pkt_get_sync_offset(const struct pt_packet_decoder \**decoder*,** +| **uint64_t \**offset*);** + +Link with *-lipt*. + + +# DESCRIPTION + +**pt_pkt_get_offset**() provides *decoder*'s current position as offset in bytes +from the beginning of *decoder*'s trace buffer in the unsigned integer variable +pointed to by *offset*. + +**pt_pkt_get_sync_offset**() provides *decoder*'s last synchronization point as +offset in bytes from the beginning of *decoder*'s trace buffer in the unsigned +integer variable pointed to by *offset*. + + +# RETURN VALUE + +Both functions return zero on success or a negative *pt_error_code* enumeration +constant in case of an error. + + +# ERRORS + +pte_invalid +: The *decoder* or *offset* argument is NULL. + +pte_nosync +: *decoder* has not been synchronized onto the trace stream. Use + **pt_pkt_sync_forward**(3), **pt_pkt_sync_backward**(3), or + **pt_pkt_sync_set**(3) to synchronize *decoder*. + + +# SEE ALSO + +**pt_pkt_alloc_decoder**(3), **pt_pkt_free_decoder**(3), +**pt_pkt_sync_forward**(3), **pt_pkt_sync_backward**(3), +**pt_pkt_sync_set**(3), **pt_pkt_next**(3) diff --git a/doc/man/pt_pkt_sync_forward.3.md b/doc/man/pt_pkt_sync_forward.3.md new file mode 100644 index 0000000000000..cf367b863bac8 --- /dev/null +++ b/doc/man/pt_pkt_sync_forward.3.md @@ -0,0 +1,115 @@ +% PT_PKT_SYNC_FORWARD(3) + +<!--- + ! Copyright (c) 2015-2019, 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_pkt_sync_forward, pt_pkt_sync_backward, pt_pkt_sync_set - synchronize an +Intel(R) Processor Trace packet decoder + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **int pt_pkt_sync_forward(struct pt_packet_decoder \**decoder*);** +| **int pt_pkt_sync_backward(struct pt_packet_decoder \**decoder*);** +| **int pt_pkt_sync_set(struct pt_packet_decoder \**decoder*,** +| **uint64_t *offset*);** + +Link with *-lipt*. + + +# DESCRIPTION + +**pt_pkt_sync_forward**() and **pt_pkt_sync_backward**() synchronize an Intel +Processor Trace (Intel PT) packet decoder pointed to by *decoder* onto the trace +stream in *decoder*'s trace buffer. They search for a Packet Stream Boundary +(PSB) packet in the trace stream and, if successful, set *decoder*'s current +position to that packet. + +**pt_pkt_sync_forward**() searches in forward direction from *decoder*'s current +position towards the end of the trace buffer. If *decoder* has been newly +allocated and has not been synchronized yet, the search starts from the +beginning of the trace. + +**pt_pkt_sync_backward**() searches in backward direction from *decoder*'s +current position towards the beginning of the trace buffer. If *decoder* has +been newly allocated and has not been synchronized yet, the search starts from +the end of the trace. + +**pt_pkt_sync_set**() sets *decoder*'s current position to *offset* bytes from +the beginning of its trace buffer. + + +# RETURN VALUE + +All synchronization functions return zero or a positive value on success or a +negative *pt_error_code* enumeration constant in case of an error. + + +# ERRORS + +pte_invalid +: The *decoder* argument is NULL. + +pte_eos +: There is no (further) PSB packet in the trace stream + (**pt_pkt_sync_forward**() and **pt_pkt_sync_backward**()) or the *offset* + argument is too big and the resulting position would be outside of + *decoder*'s trace buffer (**pt_pkt_sync_set**()). + + +# EXAMPLE + +The following example re-synchronizes an Intel PT packet decoder after decode +errors: + +~~~{.c} +int foo(struct pt_packet_decoder *decoder) { + for (;;) { + int errcode; + + errcode = pt_pkt_sync_forward(decoder); + if (errcode < 0) + return errcode; + + do { + errcode = decode(decoder); + } while (errcode >= 0); + } +} +~~~ + + +# SEE ALSO + +**pt_pkt_alloc_decoder**(3), **pt_pkt_free_decoder**(3), +**pt_pkt_get_offset**(3), **pt_pkt_get_sync_offset**(3), +**pt_pkt_get_config**(3), **pt_pkt_next**(3) diff --git a/doc/man/pt_qry_alloc_decoder.3.md b/doc/man/pt_qry_alloc_decoder.3.md new file mode 100644 index 0000000000000..1ec6b16153f56 --- /dev/null +++ b/doc/man/pt_qry_alloc_decoder.3.md @@ -0,0 +1,113 @@ +% PT_QRY_ALLOC_DECODER(3) + +<!--- + ! Copyright (c) 2015-2019, 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_alloc_decoder, pt_qry_free_decoder - allocate/free an Intel(R) Processor +Trace query decoder + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **struct pt_query_decoder \*** +| **pt_qry_alloc_decoder(const struct pt_config \**config*);** +| +| **void pt_qry_free_decoder(struct pt_query_decoder \**decoder*);** + +Link with *-lipt*. + + +# DESCRIPTION + +A query decoder decodes raw Intel Processor Trace (Intel PT) and provides +functions for querying the decoder about: + + - whether the next conditional branch was taken (or not taken) + - the destination of the next indirect branch + +This information can be used to reconstruct the execution flow of the traced +code. As long as the flow is clear, follow the flow. If the flow cannot be +determined by examining the current instruction, ask the query decoder. + +In addition, the query decoder indicates asynchronous events via the return +value of its query functions and provides an additional function to query for +such asynchronous events. See **pt_qry_cond_branch**(3), +**pt_qry_indirect_branch**(3), and **pt_qry_event**(3). + +**pt_qry_alloc_decoder**() allocates a new query decoder and returns a pointer +to it. The *config* argument points to a *pt_config* object. See +**pt_config**(3). The *config* argument will not be referenced by the returned +decoder but the trace buffer defined by the *config* argument's *begin* and +*end* fields will. + +The returned query decoder needs to be synchronized onto the trace stream +before it can be used. To synchronize the query decoder, use +**pt_qry_sync_forward**(3), **pt_qry_sync_backward**(3), or +**pt_qry_sync_set**(3). + +**pt_qry_free_decoder**() frees the Intel PT query decoder pointed to by +*decoder*. The *decoder* argument must be NULL or point to a decoder that has +been allocated by a call to **pt_qry_alloc_decoder**(). + + +# RETURN VALUE + +**pt_qry_alloc_decoder**() returns a pointer to a *pt_query_decoder* object on +success or NULL in case of an error. + + +# EXAMPLE + +~~~{.c} +int foo(const struct pt_config *config) { + struct pt_query_decoder *decoder; + errcode; + + decoder = pt_qry_alloc_decoder(config); + if (!decoder) + return pte_nomem; + + errcode = bar(decoder); + + pt_qry_free_decoder(decoder); + return errcode; +} +~~~ + + +# SEE ALSO + +**pt_config**(3), **pt_qry_sync_forward**(3), **pt_qry_sync_backward**(3), +**pt_qry_sync_set**(3), **pt_qry_get_offset**(3), **pt_qry_get_sync_offset**(3), +**pt_qry_get_config**(3), **pt_qry_cond_branch**(3), +**pt_qry_indirect_branch**(3), **pt_qry_event**(3), **pt_qry_time**(3), +**pt_qry_core_bus_ratio**(3) diff --git a/doc/man/pt_qry_cond_branch.3.md b/doc/man/pt_qry_cond_branch.3.md new file mode 100644 index 0000000000000..b1974761a3285 --- /dev/null +++ b/doc/man/pt_qry_cond_branch.3.md @@ -0,0 +1,152 @@ +% PT_QRY_COND_BRANCH(3) + +<!--- + ! Copyright (c) 2015-2019, 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_cond_branch, pt_qry_indirect_branch - query an Intel(R) Processor Trace +query decoder + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **int pt_qry_cond_branch(struct pt_query_decoder \**decoder*,** +| **int \**taken*);** +| **int pt_qry_indirect_branch(struct pt_query_decoder \**decoder*,** +| **uint64_t \**ip*); + +Link with *-lipt*. + + +# DESCRIPTION + +**pt_qry_cond_branch**() uses Intel Processor Trace (Intel PT) to determine +whether the next conditional branch in the traced code was taken or was not +taken. The *decoder* argument must point to an Intel PT query decoder. + +On success, sets the variable the *taken* argument points to a non-zero value +if the next condition branch is taken and to zero if it is not taken. + +**pt_qry_indirect_branch**() uses Intel Processor Trace (Intel PT) to determine +the destination virtual address of the next indirect branch in the traced code. + +On success, provides the destination address in the integer variable pointed to +be the *ip* argument. If the destination address has been suppressed in the +Intel PT trace, the lack of an IP is indicated in the return value by setting +the *pts_ip_suppressed* bit. + + +# RETURN VALUE + +Both functions return zero or a positive value on success or a negative +*pt_error_code* enumeration constant in case of an error. + +On success, a bit-vector of *pt_status_flag* enumeration constants is returned. +The *pt_status_flag* enumeration is declared as: + +~~~{.c} +/** Decoder status flags. */ +enum pt_status_flag { + /** There is an event pending. */ + pts_event_pending = 1 << 0, + + /** The address has been suppressed. */ + pts_ip_suppressed = 1 << 1, + + /** There is no more trace data available. */ + pts_eos = 1 << 2 +}; +~~~ + + +# ERRORS + +pte_invalid +: The *decoder* argument or the *taken* (**pt_qry_cond_branch**()) or *ip* + (**pt_qry_indirect_branch**()) argument is NULL. + +pte_eos +: Decode reached the end of the trace stream. + +pte_nosync +: The decoder has not been synchronized onto the trace stream. Use + **pt_qry_sync_forward**(3), **pt_qry_sync_backward**(3), or + **pt_qry_sync_set**(3) to synchronize *decoder*. + +pte_bad_opc +: The decoder encountered an unsupported Intel PT packet opcode. + +pte_bad_packet +: The decoder encountered an unsupported Intel PT packet payload. + +pte_bad_query +: The query does not match the data provided in the Intel PT stream. Based on + the trace, the decoder expected a call to the other query function or a call + to **pt_qry_event**(3). This usually means that execution flow + reconstruction and trace got out of sync. + + +# EXAMPLE + +The following example sketches an execution flow reconstruction loop. +Asynchronous events have been omitted. + +~~~{.c} +int foo(struct pt_query_decoder *decoder, uint64_t ip) { + for (;;) { + if (insn_is_cond_branch(ip)) { + int errcode, taken; + + errcode = pt_qry_cond_branch(decoder, &taken); + if (errcode < 0) + return errcode; + + if (taken) + ip = insn_destination(ip); + else + ip = insn_next_ip(ip); + } else if (insn_is_indirect_branch(ip)) { + int errcode; + + errcode = pt_qry_indirect_branch(decoder, &ip); + if (errcode < 0) + return errcode; + } else + ip = insn_next_ip(ip); + } +} +~~~ + + +# SEE ALSO + +**pt_qry_alloc_decoder**(3), **pt_qry_free_decoder**(3), +**pt_qry_event**(3), **pt_qry_time**(3), **pt_qry_core_bus_ratio**(3) diff --git a/doc/man/pt_qry_event.3.md b/doc/man/pt_qry_event.3.md new file mode 100644 index 0000000000000..90e3d0e1cd32c --- /dev/null +++ b/doc/man/pt_qry_event.3.md @@ -0,0 +1,291 @@ +% PT_QRY_EVENT(3) + +<!--- + ! Copyright (c) 2015-2019, 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_event, pt_insn_event, pt_blk_event - query an Intel(R) Processor Trace +decoder for an asynchronous event + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **int pt_qry_event(struct pt_query_decoder \**decoder*,** +| **struct pt_event \**event*, size_t *size*);** +| +| **int pt_insn_event(struct pt_insn_decoder \**decoder*,** +| **struct pt_event \**event*, size_t *size*);** +| +| **int pt_blk_event(struct pt_block_decoder \**decoder*,** +| **struct pt_event \**event*, size_t *size*);** + +Link with *-lipt*. + + +# DESCRIPTION + +**pt_qry_event**(), **pt_insn_event**(), and **pt_blk_event**() provide the next +pending asynchronous event in *decoder*'s Intel Processor Trace (Intel PT) +decode in the *pt_event* object pointed to by the *event* argument. + +The *size* argument must be set to *sizeof(struct pt_event)*. The function will +provide at most *size* bytes of the *pt_event* structure. A newer decoder +library may provide event types that are not yet defined. Those events may be +truncated. + +On success, detailed information about the event is provided in the *pt_event* +object pointed to by the *event* argument. The *pt_event* structure is declared +as: + +~~~{.c} +/** An event. */ +struct pt_event { + /** The type of the event. */ + enum pt_event_type type; + + /** A flag indicating that the event IP has been + * suppressed. + */ + uint32_t ip_suppressed:1; + + /** A flag indicating that the event is for status update. */ + uint32_t status_update:1; + + /** A flag indicating that the event has timing + * information. + */ + uint32_t has_tsc:1; + + /** The time stamp count of the event. + * + * This field is only valid if \@has_tsc is set. + */ + uint64_t tsc; + + /** The number of lost mtc and cyc packets. + * + * This gives an idea about the quality of the \@tsc. The + * more packets were dropped, the less precise timing is. + */ + uint32_t lost_mtc; + uint32_t lost_cyc; + + /* Reserved space for future extensions. */ + uint64_t reserved[2]; + + /** Event specific data. */ + union { + /** Event: enabled. */ + struct { + /** The address at which tracing resumes. */ + uint64_t ip; + + /** A flag indicating that tracing resumes from the IP + * at which tracing had been disabled before. + */ + uint32_t resumed:1; + } enabled; + + /** Event: disabled. */ + struct { + /** The destination of the first branch inside a + * filtered area. + * + * This field is not valid if \@ip_suppressed is set. + */ + uint64_t ip; + + /* The exact source ip needs to be determined using + * disassembly and the filter configuration. + */ + } disabled; + + [...] + } variant; +}; +~~~ + +See the *intel-pt.h* header file for more detail. The common fields of the +*pt_event* structure are described in more detail below: + +type +: The type of the event as a *pt_event_type* enumeration, which is declared + as: + +~~~{.c} +/** Event types. */ +enum pt_event_type { + /* Tracing has been enabled/disabled. */ + ptev_enabled, + ptev_disabled, + + /* Tracing has been disabled asynchronously. */ + ptev_async_disabled, + + /* An asynchronous branch, e.g. interrupt. */ + ptev_async_branch, + + /* A synchronous paging event. */ + ptev_paging, + + /* An asynchronous paging event. */ + ptev_async_paging, + + /* Trace overflow. */ + ptev_overflow, + + /* An execution mode change. */ + ptev_exec_mode, + + /* A transactional execution state change. */ + ptev_tsx, + + /* Trace Stop. */ + ptev_stop, + + /* A synchronous vmcs event. */ + ptev_vmcs, + + /* An asynchronous vmcs event. */ + ptev_async_vmcs, + + /* Execution has stopped. */ + ptev_exstop, + + /* An MWAIT operation completed. */ + ptev_mwait, + + /* A power state was entered. */ + ptev_pwre, + + /* A power state was exited. */ + ptev_pwrx, + + /* A PTWRITE event. */ + ptev_ptwrite, + + /* A timing event. */ + ptev_tick, + + /* A core:bus ratio event. */ + ptev_cbr, + + /* A maintenance event. */ + ptev_mnt +}; +~~~ + +ip_suppressed +: A flag indicating whether the *ip* field in the event-dependent part is not + valid because the value has been suppressed in the trace. + +status_update +: A flag indicating whether the event is for updating the decoder's status. + Status update events originate from Intel PT packets in PSB+. + +has_tsc +: A flag indicating that the event's timing-related fields *tsc*, *lost_mtc*, + and *lost_cyc* are valid. + +tsc +: The last time stamp count before the event. Depending on the timing + configuration, the timestamp can be more or less precise. For + cycle-accurate tracing, event packets are typically CYC-eligible so the + timestamp should be cycle-accurate. + +lost_mtc, lost_cyc +: The number of lost MTC and CYC updates. An update is lost if the decoder + was not able to process an MTC or CYC packet due to missing information. + This can be either missing calibration or missing configuration information. + The number of lost MTC and CYC updates gives a rough idea about the quality + of the *tsc* field. + +variant +: This field contains event-specific information. See the *intel-pt.h* header + file for details. + + +# RETURN VALUE + +**pt_qry_event**(), **pt_insn_event**(), and **pt_blk_event**() return zero or a +*positive value on success or a negative pt_error_code* enumeration constant in +*case of an error. + +On success, a bit-vector of *pt_status_flag* enumeration constants is returned. +The *pt_status_flag* enumeration is declared as: + +~~~{.c} +/** Decoder status flags. */ +enum pt_status_flag { + /** There is an event pending. */ + pts_event_pending = 1 << 0, + + /** The address has been suppressed. */ + pts_ip_suppressed = 1 << 1, + + /** There is no more trace data available. */ + pts_eos = 1 << 2 +}; +~~~ + + +# ERRORS + +pte_invalid +: The *decoder* or *event* argument is NULL or the *size* argument is too + small. + +pte_eos +: Decode reached the end of the trace stream. + +pte_nosync +: The decoder has not been synchronized onto the trace stream. Use + **pt_qry_sync_forward**(3), **pt_qry_sync_backward**(3), or + **pt_qry_sync_set**(3) to synchronize *decoder*. + +pte_bad_opc +: The decoder encountered an unsupported Intel PT packet opcode. + +pte_bad_packet +: The decoder encountered an unsupported Intel PT packet payload. + +pte_bad_query +: The query does not match the data provided in the Intel PT stream. Based on + the trace, the decoder expected a call to **pt_qry_cond_branch**(3) or + **pt_qry_indirect_branch**(3). This usually means that execution flow + reconstruction and trace got out of sync. + + +# SEE ALSO + +**pt_qry_alloc_decoder**(3), **pt_qry_free_decoder**(3), +**pt_qry_cond_branch**(3), **pt_qry_indirect_branch**(3), **pt_qry_time**(3), +**pt_qry_core_bus_ratio**(3), **pt_insn_next**(3), **pt_blk_next**(3) diff --git a/doc/man/pt_qry_get_offset.3.md b/doc/man/pt_qry_get_offset.3.md new file mode 100644 index 0000000000000..8a348c3c1f29a --- /dev/null +++ b/doc/man/pt_qry_get_offset.3.md @@ -0,0 +1,83 @@ +% PT_QRY_GET_OFFSET(3) + +<!--- + ! Copyright (c) 2015-2019, 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_get_offset, pt_qry_get_sync_offset - get an Intel(R) Processor Trace +query decoder's current/synchronization trace buffer offset + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **int pt_qry_get_offset(const struct pt_query_decoder \**decoder*,** +| **uint64_t \**offset*);** +| **int pt_qry_get_sync_offset(const struct pt_query_decoder \**decoder*,** +| **uint64_t \**offset*);** + +Link with *-lipt*. + + +# DESCRIPTION + +**pt_qry_get_offset**() provides *decoder*'s current position as offset in bytes +from the beginning of *decoder*'s trace buffer in the unsigned integer variable +pointed to by *offset*. + +**pt_qry_get_sync_offset**() provides *decoder*'s last synchronization point as +offset in bytes from the beginning of *decoder*'s trace buffer in the unsigned +integer variable pointed to by *offset*. + + +# RETURN VALUE + +Both functions return zero on success or a negative *pt_error_code* enumeration +constant in case of an error. + + +# ERRORS + +pte_invalid +: The *decoder* or *offset* argument is NULL. + +pte_nosync +: *decoder* has not been synchronized onto the trace stream. Use + **pt_qry_sync_forward**(3), **pt_qry_sync_backward**(3), or + **pt_qry_sync_set**(3) to synchronize *decoder*. + + +# SEE ALSO + +**pt_qry_alloc_decoder**(3), **pt_qry_free_decoder**(3), +**pt_qry_sync_forward**(3), **pt_qry_sync_backward**(3), +**pt_qry_sync_set**(3), **pt_qry_get_config**(3), **pt_qry_cond_branch**(3), +**pt_qry_indirect_branch**(3), **pt_qry_event**(3), **pt_qry_time**(3), +**pt_qry_core_bus_ratio**(3) diff --git a/doc/man/pt_qry_sync_forward.3.md b/doc/man/pt_qry_sync_forward.3.md new file mode 100644 index 0000000000000..b69acbd3831f3 --- /dev/null +++ b/doc/man/pt_qry_sync_forward.3.md @@ -0,0 +1,152 @@ +% PT_QRY_SYNC_FORWARD(3) + +<!--- + ! Copyright (c) 2015-2019, 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_sync_forward, pt_qry_sync_backward, pt_qry_sync_set - synchronize an +Intel(R) Processor Trace query decoder + + +# SYNOPSIS + +| **\#include `<intel-pt.h>`** +| +| **int pt_qry_sync_forward(struct pt_query_decoder \**decoder*,** +| **uint64_t \**ip*);** +| **int pt_qry_sync_backward(struct pt_query_decoder \**decoder*,** +| **uint64_t \**ip*);** +| **int pt_qry_sync_set(struct pt_query_decoder \**decoder*,** +| **uint64_t \**ip*, uint64_t *offset*);** + +Link with *-lipt*. + + +# DESCRIPTION + +These functions synchronize an Intel Processor Trace (Intel PT) query decoder +pointed to by *decoder* onto the trace stream in *decoder*'s trace buffer. + +They search for a Packet Stream Boundary (PSB) packet in the trace stream and, +if successful, set *decoder*'s current position and synchronization position to +that packet and start processing packets. For synchronization to be +successfull, there must be a full PSB+ header in the trace stream. + +If the *ip* argument is not NULL, these functions provide the code memory +address at which tracing starts in the variable pointed to by *ip*. If tracing +is disabled at the synchronization point, the lack of an IP is indicated in the +return value by setting the *pts_ip_suppressed* bit. + +**pt_qry_sync_forward**() searches in forward direction from *decoder*'s current +position towards the end of the trace buffer. If *decoder* has been newly +allocated and has not been synchronized yet, the search starts from the +beginning of the trace. + +**pt_qry_sync_backward**() searches in backward direction from *decoder*'s +current position towards the beginning of the trace buffer. If *decoder* has +been newly allocated and has not been synchronized yet, the search starts from +the end of the trace. + +**pt_qry_sync_set**() searches at *offset* bytes from the beginning of its trace +buffer. + + +# RETURN VALUE + +All synchronization functions return zero or a positive value on success or a +negative *pt_error_code* enumeration constant in case of an error. + +On success, a bit-vector of *pt_status_flag* enumeration constants is returned. +The *pt_status_flag* enumeration is declared as: + +~~~{.c} +/** Decoder status flags. */ +enum pt_status_flag { + /** There is an event pending. */ + pts_event_pending = 1 << 0, + + /** The address has been suppressed. */ + pts_ip_suppressed = 1 << 1, + + /** There is no more trace data available. */ + pts_eos = 1 << 2 +}; +~~~ + + +# ERRORS + +pte_invalid +: The *decoder* argument is NULL. + +pte_eos +: There is no (further) PSB+ header in the trace stream + (**pt_qry_sync_forward**() and **pt_qry_sync_backward**()) or at *offset* + bytes into the trace buffer (**pt_qry_sync_set**()). + +pte_nosync +: There is no PSB packet at *offset* bytes from the beginning of the trace + (**pt_qry_sync_set**() only). + +pte_bad_opc +: The decoder encountered an unsupported Intel PT packet opcode. + +pte_bad_packet +: The decoder encountered an unsupported Intel PT packet payload. + + +# EXAMPLE + +The following example re-synchronizes an Intel PT query decoder after decode +errors: + +~~~{.c} +int foo(struct pt_query_decoder *decoder) { + for (;;) { + int errcode; + + errcode = pt_qry_sync_forward(decoder); + if (errcode < 0) + return errcode; + + do { + errcode = decode(decoder); + } while (errcode >= 0); + } +} +~~~ + + +# SEE ALSO + +**pt_qry_alloc_decoder**(3), **pt_qry_free_decoder**(3), +**pt_qry_get_offset**(3), **pt_qry_get_sync_offset**(3), +**pt_qry_get_config**(3), **pt_qry_cond_branch**(3), +**pt_qry_indirect_branch**(3), **pt_qry_event**(3), **pt_qry_time**(3), +**pt_qry_core_bus_ratio**(3) diff --git a/doc/man/pt_qry_time.3.md b/doc/man/pt_qry_time.3.md new file mode 100644 index 0000000000000..1dc8a4f691f92 --- /dev/null +++ b/doc/man/pt_qry_time.3.md @@ -0,0 +1,128 @@ +% PT_QRY_TIME(3) + +<!--- + ! Copyright (c) 2015-2019, 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) |