|
Packit |
b1f7ae |
% PT_CONFIG(3)
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
! Copyright (c) 2015-2017, Intel Corporation
|
|
Packit |
b1f7ae |
!
|
|
Packit |
b1f7ae |
! Redistribution and use in source and binary forms, with or without
|
|
Packit |
b1f7ae |
! modification, are permitted provided that the following conditions are met:
|
|
Packit |
b1f7ae |
!
|
|
Packit |
b1f7ae |
! * Redistributions of source code must retain the above copyright notice,
|
|
Packit |
b1f7ae |
! this list of conditions and the following disclaimer.
|
|
Packit |
b1f7ae |
! * Redistributions in binary form must reproduce the above copyright notice,
|
|
Packit |
b1f7ae |
! this list of conditions and the following disclaimer in the documentation
|
|
Packit |
b1f7ae |
! and/or other materials provided with the distribution.
|
|
Packit |
b1f7ae |
! * Neither the name of Intel Corporation nor the names of its contributors
|
|
Packit |
b1f7ae |
! may be used to endorse or promote products derived from this software
|
|
Packit |
b1f7ae |
! without specific prior written permission.
|
|
Packit |
b1f7ae |
!
|
|
Packit |
b1f7ae |
! THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
Packit |
b1f7ae |
! AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
Packit |
b1f7ae |
! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
Packit |
b1f7ae |
! ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
|
|
Packit |
b1f7ae |
! LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
Packit |
b1f7ae |
! CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
Packit |
b1f7ae |
! SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
Packit |
b1f7ae |
! INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
Packit |
b1f7ae |
! CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
Packit |
b1f7ae |
! ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
Packit |
b1f7ae |
! POSSIBILITY OF SUCH DAMAGE.
|
|
Packit |
b1f7ae |
!-->
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# NAME
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
pt_config, pt_config_init, pt_cpu_errata - Intel(R) Processor Trace
|
|
Packit |
b1f7ae |
encoder/decoder configuration
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# SYNOPSIS
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
| **\#include `<intel-pt.h>`**
|
|
Packit |
b1f7ae |
|
|
|
Packit |
b1f7ae |
| **struct pt_config;**
|
|
Packit |
b1f7ae |
|
|
|
Packit |
b1f7ae |
| **void pt_config_init(struct pt_config \**config*);**
|
|
Packit |
b1f7ae |
|
|
|
Packit |
b1f7ae |
| **int pt_cpu_errata(struct pt_errata \**errata*, const struct pt_cpu \**cpu*);**
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
Link with *-lipt*.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# DESCRIPTION
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
The *pt_config* structure defines an Intel Processor Trace (Intel PT) encoder or
|
|
Packit |
b1f7ae |
decoder configuration. It is required for allocating a trace packet encoder
|
|
Packit |
b1f7ae |
(see **pt_alloc_encoder**(3)), a trace packet decoder (see
|
|
Packit |
b1f7ae |
**pt_pkt_alloc_decoder**(3)), a query decoder (see **pt_qry_alloc_decoder**(3)),
|
|
Packit |
b1f7ae |
or an instruction flow decoder (see **pt_insn_alloc_decoder**(3)).
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
**pt_config_init**() zero-initializes its *config* argument and sets *config*'s
|
|
Packit |
b1f7ae |
*size* field to *sizeof(struct pt_config)*.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
**pt_cpu_errata**() enables workarounds for known errata in its *errata*
|
|
Packit |
b1f7ae |
argument for the processor defined by its family/model/stepping in its *cpu*
|
|
Packit |
b1f7ae |
argument.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
The *pt_config* structure is declared as:
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
~~~{.c}
|
|
Packit |
b1f7ae |
/** An Intel PT decoder configuration. */
|
|
Packit |
b1f7ae |
struct pt_config {
|
|
Packit |
b1f7ae |
/** The size of the config structure in bytes. */
|
|
Packit |
b1f7ae |
size_t size;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** The trace buffer begin address. */
|
|
Packit |
b1f7ae |
uint8_t *begin;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** The trace buffer end address. */
|
|
Packit |
b1f7ae |
uint8_t *end;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** An optional callback for handling unknown packets.
|
|
Packit |
b1f7ae |
*
|
|
Packit |
b1f7ae |
* If \@callback is not NULL, it is called for any unknown
|
|
Packit |
b1f7ae |
* opcode.
|
|
Packit |
b1f7ae |
*/
|
|
Packit |
b1f7ae |
struct {
|
|
Packit |
b1f7ae |
/** The callback function.
|
|
Packit |
b1f7ae |
*
|
|
Packit |
b1f7ae |
* It shall decode the packet at \@pos into \@unknown.
|
|
Packit |
b1f7ae |
* It shall return the number of bytes read upon success.
|
|
Packit |
b1f7ae |
* It shall return a negative pt_error_code otherwise.
|
|
Packit |
b1f7ae |
* The below context is passed as \@context.
|
|
Packit |
b1f7ae |
*/
|
|
Packit |
b1f7ae |
int (*callback)(struct pt_packet_unknown *unknown,
|
|
Packit |
b1f7ae |
const struct pt_config *config,
|
|
Packit |
b1f7ae |
const uint8_t *pos, void *context);
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** The user-defined context for this configuration. */
|
|
Packit |
b1f7ae |
void *context;
|
|
Packit |
b1f7ae |
} decode;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** The cpu on which Intel PT has been recorded. */
|
|
Packit |
b1f7ae |
struct pt_cpu cpu;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** The errata to apply when encoding or decoding Intel PT. */
|
|
Packit |
b1f7ae |
struct pt_errata errata;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** The CTC frequency.
|
|
Packit |
b1f7ae |
*
|
|
Packit |
b1f7ae |
* This is only required if MTC packets have been enabled in
|
|
Packit |
b1f7ae |
* IA32_RTIT_CTRL.MTCEn.
|
|
Packit |
b1f7ae |
*/
|
|
Packit |
b1f7ae |
uint32_t cpuid_0x15_eax, cpuid_0x15_ebx;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** The MTC frequency as defined in IA32_RTIT_CTL.MTCFreq.
|
|
Packit |
b1f7ae |
*
|
|
Packit |
b1f7ae |
* This is only required if MTC packets have been enabled in
|
|
Packit |
b1f7ae |
* IA32_RTIT_CTRL.MTCEn.
|
|
Packit |
b1f7ae |
*/
|
|
Packit |
b1f7ae |
uint8_t mtc_freq;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** The nominal frequency as defined in
|
|
Packit |
b1f7ae |
* MSR_PLATFORM_INFO[15:8].
|
|
Packit |
b1f7ae |
*
|
|
Packit |
b1f7ae |
* This is only required if CYC packets have been enabled in
|
|
Packit |
b1f7ae |
* IA32_RTIT_CTRL.CYCEn.
|
|
Packit |
b1f7ae |
*
|
|
Packit |
b1f7ae |
* If zero, timing calibration will only be able to use MTC
|
|
Packit |
b1f7ae |
* and CYC packets.
|
|
Packit |
b1f7ae |
*
|
|
Packit |
b1f7ae |
* If not zero, timing calibration will also be able to use
|
|
Packit |
b1f7ae |
* CBR packets.
|
|
Packit |
b1f7ae |
*/
|
|
Packit |
b1f7ae |
uint8_t nom_freq;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** A collection of decoder-specific flags. */
|
|
Packit |
b1f7ae |
struct pt_conf_flags flags;
|
|
Packit |
b1f7ae |
};
|
|
Packit |
b1f7ae |
~~~
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
The fields of the *pt_config* structure are described in more detail below:
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
size
|
|
Packit |
b1f7ae |
: The size of the *pt_config* structure for backward and forward
|
|
Packit |
b1f7ae |
compatibility. Set it to *sizeof(struct pt_config)*.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
begin, end
|
|
Packit |
b1f7ae |
: The begin and end of a user-allocated memory buffer; *begin* points to
|
|
Packit |
b1f7ae |
the first byte of the buffer, *end* points to one past the last byte in the
|
|
Packit |
b1f7ae |
buffer.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
The packet encoder will generate Intel PT packets into the memory buffer.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
The decoders expect the buffer to contain raw Intel PT packets. They decode
|
|
Packit |
b1f7ae |
directly from the buffer and expect the buffer to remain valid until the
|
|
Packit |
b1f7ae |
decoder has been freed.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
decode
|
|
Packit |
b1f7ae |
: An optional packet decode callback function. If *decode.callback* is not
|
|
Packit |
b1f7ae |
NULL, it will be called for any unknown packet with the decoder
|
|
Packit |
b1f7ae |
configuration, the current decoder position and with a user-defined context
|
|
Packit |
b1f7ae |
provided in *callback.context* as arguments.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
If the callback function is able to decode the packet, it shall return the
|
|
Packit |
b1f7ae |
size of the decoded packet and provide details in a *pt_packet_unknown*
|
|
Packit |
b1f7ae |
object.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
If the packet cannot be decoded, the callback function shall return a
|
|
Packit |
b1f7ae |
negative *pt_error_code* enumeration constant.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
The *pt_packet_unknown* object can be used to provide user-defined
|
|
Packit |
b1f7ae |
information back to the user when using the packet decoder to iterate over
|
|
Packit |
b1f7ae |
Intel PT packets. Other decoders ignore this information but will skip
|
|
Packit |
b1f7ae |
the packet if a non-zero size is returned by the callback function.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
cpu
|
|
Packit |
b1f7ae |
: The processor on which the trace has been collected or for which the trace
|
|
Packit |
b1f7ae |
should be generated. The processor is identified by its family, model, and
|
|
Packit |
b1f7ae |
stepping.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
~~~{.c}
|
|
Packit |
b1f7ae |
/** A cpu vendor. */
|
|
Packit |
b1f7ae |
enum pt_cpu_vendor {
|
|
Packit |
b1f7ae |
pcv_unknown,
|
|
Packit |
b1f7ae |
pcv_intel
|
|
Packit |
b1f7ae |
};
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** A cpu identifier. */
|
|
Packit |
b1f7ae |
struct pt_cpu {
|
|
Packit |
b1f7ae |
/** The cpu vendor. */
|
|
Packit |
b1f7ae |
enum pt_cpu_vendor vendor;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** The cpu family. */
|
|
Packit |
b1f7ae |
uint16_t family;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** The cpu model. */
|
|
Packit |
b1f7ae |
uint8_t model;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** The stepping. */
|
|
Packit |
b1f7ae |
uint8_t stepping;
|
|
Packit |
b1f7ae |
};
|
|
Packit |
b1f7ae |
~~~
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
errata
|
|
Packit |
b1f7ae |
: The errata workarounds to be applied by the trace encoder or decoder that
|
|
Packit |
b1f7ae |
is created using this configuration.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
The *pt_errata* structure is a collection of one-bit-fields, one for each
|
|
Packit |
b1f7ae |
supported erratum. Duplicate errata are indicated by comments for the
|
|
Packit |
b1f7ae |
erratum for which the workaround was first implemented. Set the field of an
|
|
Packit |
b1f7ae |
erratum to enable the correspondig workaround.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
The *pt_errata* structure is declared as:
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
~~~{.c}
|
|
Packit |
b1f7ae |
/** A collection of Intel PT errata. */
|
|
Packit |
b1f7ae |
struct pt_errata {
|
|
Packit |
b1f7ae |
/** BDM70: Intel(R) Processor Trace PSB+ Packets May Contain
|
|
Packit |
b1f7ae |
* Unexpected Packets.
|
|
Packit |
b1f7ae |
*
|
|
Packit |
b1f7ae |
* Same as: SKD024.
|
|
Packit |
b1f7ae |
*
|
|
Packit |
b1f7ae |
* Some Intel Processor Trace packets should be issued only
|
|
Packit |
b1f7ae |
* between TIP.PGE and TIP.PGD packets. Due to this erratum,
|
|
Packit |
b1f7ae |
* when a TIP.PGE packet is generated it may be preceded by a
|
|
Packit |
b1f7ae |
* PSB+ that incorrectly includes FUP and MODE.Exec packets.
|
|
Packit |
b1f7ae |
*/
|
|
Packit |
b1f7ae |
uint32_t bdm70:1;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
/** BDM64: An Incorrect LBR or Intel(R) Processor Trace Packet
|
|
Packit |
b1f7ae |
* May Be Recorded Following a Transactional Abort.
|
|
Packit |
b1f7ae |
*
|
|
Packit |
b1f7ae |
* Use of Intel(R) Transactional Synchronization Extensions
|
|
Packit |
b1f7ae |
* (Intel(R) TSX) may result in a transactional abort. If an
|
|
Packit |
b1f7ae |
* abort occurs immediately following a branch instruction,
|
|
Packit |
b1f7ae |
* an incorrect branch target may be logged in an LBR (Last
|
|
Packit |
b1f7ae |
* Branch Record) or in an Intel(R) Processor Trace (Intel(R)
|
|
Packit |
b1f7ae |
* PT) packet before the LBR or Intel PT packet produced by
|
|
Packit |
b1f7ae |
* the abort.
|
|
Packit |
b1f7ae |
*/
|
|
Packit |
b1f7ae |
uint32_t bdm64:1;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
[...]
|
|
Packit |
b1f7ae |
};
|
|
Packit |
b1f7ae |
~~~
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
cpuid_0x15_eax, cpuid_0x15_ebx
|
|
Packit |
b1f7ae |
: The values of *eax* and *ebx* on a *cpuid* call for leaf *0x15*.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
The value *ebx/eax* gives the ratio of the Core Crystal Clock (CTC) to
|
|
Packit |
b1f7ae |
Timestamp Counter (TSC) frequency.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
This field is ignored by the packet encoder and packet decoder. It is
|
|
Packit |
b1f7ae |
required for other decoders if Mini Time Counter (MTC) packets are enabled
|
|
Packit |
b1f7ae |
in the collected trace.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
mtc_freq
|
|
Packit |
b1f7ae |
: The Mini Time Counter (MTC) frequency as defined in *IA32_RTIT_CTL.MTCFreq*.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
This field is ignored by the packet encoder and packet decoder. It is
|
|
Packit |
b1f7ae |
required for other decoders if Mini Time Counter (MTC) packets are enabled
|
|
Packit |
b1f7ae |
in the collected trace.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
nom_freq
|
|
Packit |
b1f7ae |
: The nominal or max non-turbo frequency.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
This field is ignored by the packet encoder and packet decoder. It is
|
|
Packit |
b1f7ae |
used by other decoders if Cycle Count (CYC) packets are enabled to improve
|
|
Packit |
b1f7ae |
timing calibration for cycle-accurate tracing.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
If the field is zero, the time tracking algorithm will use Mini Time
|
|
Packit |
b1f7ae |
Counter (MTC) and Cycle Count (CYC) packets for calibration.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
If the field is non-zero, the time tracking algorithm will additionally be
|
|
Packit |
b1f7ae |
able to calibrate at Core:Bus Ratio (CBR) packets.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
flags
|
|
Packit |
b1f7ae |
: A collection of decoder-specific configuration flags.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# RETURN VALUE
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
**pt_cpu_errata**() returns zero on success or a negative *pt_error_code*
|
|
Packit |
b1f7ae |
enumeration constant otherwise.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# ERRORS
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
**pt_cpu_errata**() may return the following errors:
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
pte_invalid
|
|
Packit |
b1f7ae |
: The *errata* or *cpu* argument is NULL.
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# EXAMPLE
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
~~~{.c}
|
|
Packit |
b1f7ae |
int foo(uint8_t *trace_buffer, size_t size, struct pt_cpu cpu) {
|
|
Packit |
b1f7ae |
struct pt_config config;
|
|
Packit |
b1f7ae |
int errcode;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
pt_config_init(&config);
|
|
Packit |
b1f7ae |
config.begin = trace_buffer;
|
|
Packit |
b1f7ae |
config.end = trace_buffer + size;
|
|
Packit |
b1f7ae |
config.cpu = cpu;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
errcode = pt_cpu_errata(&config.errata, &config.cpu);
|
|
Packit |
b1f7ae |
if (errcode < 0)
|
|
Packit |
b1f7ae |
return errcode;
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
[...]
|
|
Packit |
b1f7ae |
}
|
|
Packit |
b1f7ae |
~~~
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
# SEE ALSO
|
|
Packit |
b1f7ae |
|
|
Packit |
b1f7ae |
**pt_alloc_encoder**(3), **pt_pkt_alloc_decoder**(3),
|
|
Packit |
b1f7ae |
**pt_qry_alloc_decoder**(3), **pt_insn_alloc_decoder**(3)
|