tjh.dev / kernel
Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

perf intel-pt: Improve man page format

Improve format of config terms and section references.

Reviewed-by: Andi Kleen <ak@linux.intel.com>
Signed-off-by: Adrian Hunter <adrian.hunter@intel.com>
Acked-by: Ian Rogers <irogers@google.com>
Cc: Jiri Olsa <jolsa@kernel.org>
Cc: Kan Liang <kan.liang@linux.intel.com>
Cc: Leo Yan <leo.yan@arm.com>
Cc: Namhyung Kim <namhyung@kernel.org>
Link: https://lore.kernel.org/r/20241216070244.14450-6-adrian.hunter@intel.com
Signed-off-by: Arnaldo Carvalho de Melo <acme@redhat.com>

authored by

Adrian Hunter and committed by
Arnaldo Carvalho de Melo f38ec227 bf66b5fd

+267 -219
+267 -219
tools/perf/Documentation/perf-intel-pt.txt
··· 151 151 There are two ways that instructions-per-cycle (IPC) can be calculated depending 152 152 on the recording. 153 153 154 - If the 'cyc' config term (see config terms section below) was used, then IPC 154 + If the 'cyc' config term (see <<_config_terms,config terms>> section below) was used, then IPC 155 155 and cycle events are calculated using the cycle count from CYC packets, otherwise 156 156 MTC packets are used - refer to the 'mtc' config term. When MTC is used, however, 157 157 the values are less accurate because the timing is less accurate. ··· 239 239 240 240 -e intel_pt/tsc=1,noretcomp=0/ 241 241 242 - Note there are now new config terms - see section 'config terms' further below. 242 + Note there are other config terms - see section <<_config_terms,config terms>> further below. 243 243 244 244 The config terms are listed in /sys/devices/intel_pt/format. They are bit 245 245 fields within the config member of the struct perf_event_attr which is ··· 311 311 config terms 312 312 ~~~~~~~~~~~~ 313 313 314 - The June 2015 version of Intel 64 and IA-32 Architectures Software Developer 315 - Manuals, Chapter 36 Intel Processor Trace, defined new Intel PT features. 316 - Some of the features are reflect in new config terms. All the config terms are 317 - described below. 318 - 319 - tsc Always supported. Produces TSC timestamp packets to provide 320 - timing information. In some cases it is possible to decode 321 - without timing information, for example a per-thread context 322 - that does not overlap executable memory maps. 323 - 324 - The default config selects tsc (i.e. tsc=1). 325 - 326 - noretcomp Always supported. Disables "return compression" so a TIP packet 327 - is produced when a function returns. Causes more packets to be 328 - produced but might make decoding more reliable. 329 - 330 - The default config does not select noretcomp (i.e. noretcomp=0). 331 - 332 - psb_period Allows the frequency of PSB packets to be specified. 333 - 334 - The PSB packet is a synchronization packet that provides a 335 - starting point for decoding or recovery from errors. 336 - 337 - Support for psb_period is indicated by: 338 - 339 - /sys/bus/event_source/devices/intel_pt/caps/psb_cyc 340 - 341 - which contains "1" if the feature is supported and "0" 342 - otherwise. 343 - 344 - Valid values are given by: 345 - 346 - /sys/bus/event_source/devices/intel_pt/caps/psb_periods 347 - 348 - which contains a hexadecimal value, the bits of which represent 349 - valid values e.g. bit 2 set means value 2 is valid. 350 - 351 - The psb_period value is converted to the approximate number of 352 - trace bytes between PSB packets as: 353 - 354 - 2 ^ (value + 11) 355 - 356 - e.g. value 3 means 16KiB bytes between PSBs 357 - 358 - If an invalid value is entered, the error message 359 - will give a list of valid values e.g. 360 - 361 - $ perf record -e intel_pt/psb_period=15/u uname 362 - Invalid psb_period for intel_pt. Valid values are: 0-5 363 - 364 - If MTC packets are selected, the default config selects a value 365 - of 3 (i.e. psb_period=3) or the nearest lower value that is 366 - supported (0 is always supported). Otherwise the default is 0. 367 - 368 - If decoding is expected to be reliable and the buffer is large 369 - then a large PSB period can be used. 370 - 371 - Because a TSC packet is produced with PSB, the PSB period can 372 - also affect the granularity to timing information in the absence 373 - of MTC or CYC. 374 - 375 - mtc Produces MTC timing packets. 376 - 377 - MTC packets provide finer grain timestamp information than TSC 378 - packets. MTC packets record time using the hardware crystal 379 - clock (CTC) which is related to TSC packets using a TMA packet. 380 - 381 - Support for this feature is indicated by: 382 - 383 - /sys/bus/event_source/devices/intel_pt/caps/mtc 384 - 385 - which contains "1" if the feature is supported and 386 - "0" otherwise. 387 - 388 - The frequency of MTC packets can also be specified - see 389 - mtc_period below. 390 - 391 - mtc_period Specifies how frequently MTC packets are produced - see mtc 392 - above for how to determine if MTC packets are supported. 393 - 394 - Valid values are given by: 395 - 396 - /sys/bus/event_source/devices/intel_pt/caps/mtc_periods 397 - 398 - which contains a hexadecimal value, the bits of which represent 399 - valid values e.g. bit 2 set means value 2 is valid. 400 - 401 - The mtc_period value is converted to the MTC frequency as: 402 - 403 - CTC-frequency / (2 ^ value) 404 - 405 - e.g. value 3 means one eighth of CTC-frequency 406 - 407 - Where CTC is the hardware crystal clock, the frequency of which 408 - can be related to TSC via values provided in cpuid leaf 0x15. 409 - 410 - If an invalid value is entered, the error message 411 - will give a list of valid values e.g. 412 - 413 - $ perf record -e intel_pt/mtc_period=15/u uname 414 - Invalid mtc_period for intel_pt. Valid values are: 0,3,6,9 415 - 416 - The default value is 3 or the nearest lower value 417 - that is supported (0 is always supported). 418 - 419 - cyc Produces CYC timing packets. 420 - 421 - CYC packets provide even finer grain timestamp information than 422 - MTC and TSC packets. A CYC packet contains the number of CPU 423 - cycles since the last CYC packet. Unlike MTC and TSC packets, 424 - CYC packets are only sent when another packet is also sent. 425 - 426 - Support for this feature is indicated by: 427 - 428 - /sys/bus/event_source/devices/intel_pt/caps/psb_cyc 429 - 430 - which contains "1" if the feature is supported and 431 - "0" otherwise. 432 - 433 - The number of CYC packets produced can be reduced by specifying 434 - a threshold - see cyc_thresh below. 435 - 436 - cyc_thresh Specifies how frequently CYC packets are produced - see cyc 437 - above for how to determine if CYC packets are supported. 438 - 439 - Valid cyc_thresh values are given by: 440 - 441 - /sys/bus/event_source/devices/intel_pt/caps/cycle_thresholds 442 - 443 - which contains a hexadecimal value, the bits of which represent 444 - valid values e.g. bit 2 set means value 2 is valid. 445 - 446 - The cyc_thresh value represents the minimum number of CPU cycles 447 - that must have passed before a CYC packet can be sent. The 448 - number of CPU cycles is: 449 - 450 - 2 ^ (value - 1) 451 - 452 - e.g. value 4 means 8 CPU cycles must pass before a CYC packet 453 - can be sent. Note a CYC packet is still only sent when another 454 - packet is sent, not at, e.g. every 8 CPU cycles. 455 - 456 - If an invalid value is entered, the error message 457 - will give a list of valid values e.g. 458 - 459 - $ perf record -e intel_pt/cyc,cyc_thresh=15/u uname 460 - Invalid cyc_thresh for intel_pt. Valid values are: 0-12 461 - 462 - CYC packets are not requested by default. 463 - 464 - pt Specifies pass-through which enables the 'branch' config term. 465 - 466 - The default config selects 'pt' if it is available, so a user will 467 - never need to specify this term. 468 - 469 - branch Enable branch tracing. Branch tracing is enabled by default so to 470 - disable branch tracing use 'branch=0'. 471 - 472 - The default config selects 'branch' if it is available. 473 - 474 - ptw Enable PTWRITE packets which are produced when a ptwrite instruction 475 - is executed. 476 - 477 - Support for this feature is indicated by: 478 - 479 - /sys/bus/event_source/devices/intel_pt/caps/ptwrite 480 - 481 - which contains "1" if the feature is supported and 482 - "0" otherwise. 483 - 484 - As an alternative, refer to "Emulated PTWRITE" further below. 485 - 486 - fup_on_ptw Enable a FUP packet to follow the PTWRITE packet. The FUP packet 487 - provides the address of the ptwrite instruction. In the absence of 488 - fup_on_ptw, the decoder will use the address of the previous branch 489 - if branch tracing is enabled, otherwise the address will be zero. 490 - Note that fup_on_ptw will work even when branch tracing is disabled. 491 - 492 - pwr_evt Enable power events. The power events provide information about 493 - changes to the CPU C-state. 494 - 495 - Support for this feature is indicated by: 496 - 497 - /sys/bus/event_source/devices/intel_pt/caps/power_event_trace 498 - 499 - which contains "1" if the feature is supported and 500 - "0" otherwise. 501 - 502 - event Enable Event Trace. The events provide information about asynchronous 503 - events. 504 - 505 - Support for this feature is indicated by: 506 - 507 - /sys/bus/event_source/devices/intel_pt/caps/event_trace 508 - 509 - which contains "1" if the feature is supported and 510 - "0" otherwise. 511 - 512 - notnt Disable TNT packets. Without TNT packets, it is not possible to walk 513 - executable code to reconstruct control flow, however FUP, TIP, TIP.PGE 514 - and TIP.PGD packets still indicate asynchronous control flow, and (if 515 - return compression is disabled - see noretcomp) return statements. 516 - The advantage of eliminating TNT packets is reducing the size of the 517 - trace and corresponding tracing overhead. 518 - 519 - Support for this feature is indicated by: 520 - 521 - /sys/bus/event_source/devices/intel_pt/caps/tnt_disable 522 - 523 - which contains "1" if the feature is supported and 524 - "0" otherwise. 314 + Config terms are parameters specified with the -e intel_pt// event option, 315 + for example: 316 + 317 + -e intel_pt/cyc/ 318 + 319 + which selects cycle accurate mode. Each config term can have a value which 320 + defaults to 1, so the above is the same as: 321 + 322 + -e intel_pt/cyc=1/ 323 + 324 + Some terms are set by default, so must be set to 0 to turn them off. For 325 + example, to turn off branch tracing: 326 + 327 + -e intel_pt/branch=0/ 328 + 329 + Multiple config terms are separated by commas, for example: 330 + 331 + -e intel_pt/cyc,mtc_period=9/ 332 + 333 + There are also common config terms, see linkperf:perf-record[1] documentation. 334 + 335 + Intel PT config terms are described below. 336 + 337 + *tsc*:: 338 + Always supported. Produces TSC timestamp packets to provide 339 + timing information. In some cases it is possible to decode 340 + without timing information, for example a per-thread context 341 + that does not overlap executable memory maps. 342 + + 343 + The default config selects tsc (i.e. tsc=1). 344 + 345 + *noretcomp*:: 346 + Always supported. Disables "return compression" so a TIP packet 347 + is produced when a function returns. Causes more packets to be 348 + produced but might make decoding more reliable. 349 + + 350 + The default config does not select noretcomp (i.e. noretcomp=0). 351 + 352 + *psb_period*:: 353 + Allows the frequency of PSB packets to be specified. 354 + + 355 + The PSB packet is a synchronization packet that provides a 356 + starting point for decoding or recovery from errors. 357 + + 358 + Support for psb_period is indicated by: 359 + + 360 + /sys/bus/event_source/devices/intel_pt/caps/psb_cyc 361 + + 362 + which contains "1" if the feature is supported and "0" 363 + otherwise. 364 + + 365 + Valid values are given by: 366 + + 367 + /sys/bus/event_source/devices/intel_pt/caps/psb_periods 368 + + 369 + which contains a hexadecimal value, the bits of which represent 370 + valid values e.g. bit 2 set means value 2 is valid. 371 + + 372 + The psb_period value is converted to the approximate number of 373 + trace bytes between PSB packets as: 374 + + 375 + 2 ^ (value + 11) 376 + + 377 + e.g. value 3 means 16KiB bytes between PSBs 378 + + 379 + If an invalid value is entered, the error message 380 + will give a list of valid values e.g. 381 + + 382 + $ perf record -e intel_pt/psb_period=15/u uname 383 + Invalid psb_period for intel_pt. Valid values are: 0-5 384 + + 385 + If MTC packets are selected, the default config selects a value 386 + of 3 (i.e. psb_period=3) or the nearest lower value that is 387 + supported (0 is always supported). Otherwise the default is 0. 388 + + 389 + If decoding is expected to be reliable and the buffer is large 390 + then a large PSB period can be used. 391 + + 392 + Because a TSC packet is produced with PSB, the PSB period can 393 + also affect the granularity to timing information in the absence 394 + of MTC or CYC. 395 + 396 + *mtc*:: 397 + Produces MTC timing packets. 398 + + 399 + MTC packets provide finer grain timestamp information than TSC 400 + packets. MTC packets record time using the hardware crystal 401 + clock (CTC) which is related to TSC packets using a TMA packet. 402 + + 403 + Support for this feature is indicated by: 404 + + 405 + /sys/bus/event_source/devices/intel_pt/caps/mtc 406 + + 407 + which contains "1" if the feature is supported and 408 + "0" otherwise. 409 + + 410 + The frequency of MTC packets can also be specified - see 411 + mtc_period below. 412 + 413 + *mtc_period*:: 414 + Specifies how frequently MTC packets are produced - see mtc 415 + above for how to determine if MTC packets are supported. 416 + + 417 + Valid values are given by: 418 + + 419 + /sys/bus/event_source/devices/intel_pt/caps/mtc_periods 420 + + 421 + which contains a hexadecimal value, the bits of which represent 422 + valid values e.g. bit 2 set means value 2 is valid. 423 + + 424 + The mtc_period value is converted to the MTC frequency as: 425 + 426 + CTC-frequency / (2 ^ value) 427 + + 428 + e.g. value 3 means one eighth of CTC-frequency 429 + + 430 + Where CTC is the hardware crystal clock, the frequency of which 431 + can be related to TSC via values provided in cpuid leaf 0x15. 432 + + 433 + If an invalid value is entered, the error message 434 + will give a list of valid values e.g. 435 + + 436 + $ perf record -e intel_pt/mtc_period=15/u uname 437 + Invalid mtc_period for intel_pt. Valid values are: 0,3,6,9 438 + + 439 + The default value is 3 or the nearest lower value 440 + that is supported (0 is always supported). 441 + 442 + *cyc*:: 443 + Produces CYC timing packets. 444 + + 445 + CYC packets provide even finer grain timestamp information than 446 + MTC and TSC packets. A CYC packet contains the number of CPU 447 + cycles since the last CYC packet. Unlike MTC and TSC packets, 448 + CYC packets are only sent when another packet is also sent. 449 + + 450 + Support for this feature is indicated by: 451 + + 452 + /sys/bus/event_source/devices/intel_pt/caps/psb_cyc 453 + + 454 + which contains "1" if the feature is supported and 455 + "0" otherwise. 456 + + 457 + The number of CYC packets produced can be reduced by specifying 458 + a threshold - see cyc_thresh below. 459 + 460 + *cyc_thresh*:: 461 + Specifies how frequently CYC packets are produced - see cyc 462 + above for how to determine if CYC packets are supported. 463 + + 464 + Valid cyc_thresh values are given by: 465 + + 466 + /sys/bus/event_source/devices/intel_pt/caps/cycle_thresholds 467 + + 468 + which contains a hexadecimal value, the bits of which represent 469 + valid values e.g. bit 2 set means value 2 is valid. 470 + + 471 + The cyc_thresh value represents the minimum number of CPU cycles 472 + that must have passed before a CYC packet can be sent. The 473 + number of CPU cycles is: 474 + + 475 + 2 ^ (value - 1) 476 + + 477 + e.g. value 4 means 8 CPU cycles must pass before a CYC packet 478 + can be sent. Note a CYC packet is still only sent when another 479 + packet is sent, not at, e.g. every 8 CPU cycles. 480 + + 481 + If an invalid value is entered, the error message 482 + will give a list of valid values e.g. 483 + + 484 + $ perf record -e intel_pt/cyc,cyc_thresh=15/u uname 485 + Invalid cyc_thresh for intel_pt. Valid values are: 0-12 486 + + 487 + CYC packets are not requested by default. 488 + 489 + *pt*:: 490 + Specifies pass-through which enables the 'branch' config term. 491 + + 492 + The default config selects 'pt' if it is available, so a user will 493 + never need to specify this term. 494 + 495 + *branch*:: 496 + Enable branch tracing. Branch tracing is enabled by default so to 497 + disable branch tracing use 'branch=0'. 498 + + 499 + The default config selects 'branch' if it is available. 500 + 501 + *ptw*:: 502 + Enable PTWRITE packets which are produced when a ptwrite instruction 503 + is executed. 504 + + 505 + Support for this feature is indicated by: 506 + + 507 + /sys/bus/event_source/devices/intel_pt/caps/ptwrite 508 + + 509 + which contains "1" if the feature is supported and 510 + "0" otherwise. 511 + + 512 + As an alternative, refer to "Emulated PTWRITE" further below. 513 + 514 + *fup_on_ptw*:: 515 + Enable a FUP packet to follow the PTWRITE packet. The FUP packet 516 + provides the address of the ptwrite instruction. In the absence of 517 + fup_on_ptw, the decoder will use the address of the previous branch 518 + if branch tracing is enabled, otherwise the address will be zero. 519 + Note that fup_on_ptw will work even when branch tracing is disabled. 520 + 521 + *pwr_evt*:: 522 + Enable power events. The power events provide information about 523 + changes to the CPU C-state. 524 + + 525 + Support for this feature is indicated by: 526 + + 527 + /sys/bus/event_source/devices/intel_pt/caps/power_event_trace 528 + + 529 + which contains "1" if the feature is supported and 530 + "0" otherwise. 531 + 532 + *event*:: 533 + Enable Event Trace. The events provide information about asynchronous 534 + events. 535 + + 536 + Support for this feature is indicated by: 537 + + 538 + /sys/bus/event_source/devices/intel_pt/caps/event_trace 539 + + 540 + which contains "1" if the feature is supported and 541 + "0" otherwise. 542 + 543 + *notnt*:: 544 + Disable TNT packets. Without TNT packets, it is not possible to walk 545 + executable code to reconstruct control flow, however FUP, TIP, TIP.PGE 546 + and TIP.PGD packets still indicate asynchronous control flow, and (if 547 + return compression is disabled - see noretcomp) return statements. 548 + The advantage of eliminating TNT packets is reducing the size of the 549 + trace and corresponding tracing overhead. 550 + + 551 + Support for this feature is indicated by: 552 + + 553 + /sys/bus/event_source/devices/intel_pt/caps/tnt_disable 554 + + 555 + which contains "1" if the feature is supported and 556 + "0" otherwise. 557 + 558 + 559 + config terms on other events 560 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 561 + 562 + Some Intel PT features work with other events, features such as AUX area sampling 563 + and PEBS-via-PT. In those cases, the other events can have config terms below: 564 + 565 + *aux-sample-size*:: 566 + Used to set the AUX area sample size, refer to the section 567 + <<_aux_area_sampling_option,AUX area sampling option>> 568 + 569 + *aux-output*:: 570 + Used to select PEBS-via-PT, refer to the 571 + section <<_pebs_via_intel_pt,PEBS via Intel PT>> 525 572 526 573 527 574 AUX area sampling option ··· 643 596 nor snapshot size is specified, then the default is 4MiB for privileged users 644 597 (or if /proc/sys/kernel/perf_event_paranoid < 0), 128KiB for unprivileged users. 645 598 If an unprivileged user does not specify mmap pages, the mmap pages will be 646 - reduced as described in the 'new auxtrace mmap size option' section below. 599 + reduced as described in the <<_new_auxtrace_mmap_size_option,new auxtrace mmap size option>> 600 + section below. 647 601 648 602 The snapshot size is displayed if the option -vv is used e.g. 649 603 ··· 1000 952 1001 953 Note that "instructions", "cycles", "branches" and "transactions" events 1002 954 depend on code flow packets which can be disabled by using the config term 1003 - "branch=0". Refer to the config terms section above. 955 + "branch=0". Refer to the <<_config_terms,config terms>> section above. 1004 956 1005 957 "ptwrite" events record the payload of the ptwrite instruction and whether 1006 958 "fup_on_ptw" was used. "ptwrite" events depend on PTWRITE packets which are 1007 - recorded only if the "ptw" config term was used. Refer to the config terms 959 + recorded only if the "ptw" config term was used. Refer to the <<_config_terms,config terms>> 1008 960 section above. perf script "synth" field displays "ptwrite" information like 1009 961 this: "ip: 0 payload: 0x123456789abcdef0" where "ip" is 1 if "fup_on_ptw" was 1010 962 used. ··· 1012 964 "Power" events correspond to power event packets and CBR (core-to-bus ratio) 1013 965 packets. While CBR packets are always recorded when tracing is enabled, power 1014 966 event packets are recorded only if the "pwr_evt" config term was used. Refer to 1015 - the config terms section above. The power events record information about 967 + the <<_config_terms,config terms>> section above. The power events record information about 1016 968 C-state changes, whereas CBR is indicative of CPU frequency. perf script 1017 969 "event,synth" fields display information like this: 1018 970 ··· 1168 1120 - asynchronous branches such as interrupts 1169 1121 - indirect branches 1170 1122 - function return target address *if* the noretcomp config term (refer 1171 - config terms section) was used 1123 + <<_config_terms,config terms>> section) was used 1172 1124 - start of (control-flow) tracing 1173 1125 - end of (control-flow) tracing, if it is not out of context 1174 1126 - power events, ptwrite, transaction start and abort ··· 1181 1133 less detail. The decoder decodes only extended PSB (PSB+) packets, getting the 1182 1134 instruction pointer if there is a FUP packet within PSB+ (i.e. between PSB and 1183 1135 PSBEND). Note PSB packets occur regularly in the trace based on the psb_period 1184 - config term (refer config terms section). There will be a FUP packet if the 1136 + config term (refer <<_config_terms,config terms>> section). There will be a FUP packet if the 1185 1137 PSB+ occurs while control flow is being traced. 1186 1138 1187 1139 What will *not* be decoded with the qq option: