Commit fa9bc517 authored by Yujie Liu's avatar Yujie Liu Committed by Namhyung Kim
Browse files

perf script: Update brstack syntax documentation 



The following commits added new fields/flags to the branch stack field
list:

commit 1f48989c ("perf script: Output branch sample type")
commit 6ade6c64 ("perf script: Show branch speculation info")
commit 1e66dcff ("perf script: Add not taken event for branch stack")

Update brstack syntax documentation to be consistent with the latest
branch stack field list. Improve the descriptions to help users
interpret the fields accurately.

Signed-off-by: default avatarYujie Liu <yujie.liu@intel.com>
Reviewed-by: default avatarLeo Yan <leo.yan@arm.com>
Reviewed-by: default avatarSandipan Das <sandipan.das@amd.com>
Link: https://lore.kernel.org/r/20250312072329.419020-1-yujie.liu@intel.com


Signed-off-by: default avatarNamhyung Kim <namhyung@kernel.org>
parent 2f39edec

tools/perf/Documentation/perf-script.txt

+16 −7
Original line number Diff line number Diff line
@@ -239,13 +239,22 @@ OPTIONS 
	i.e., -F "" is not allowed.



	The brstack output includes branch related information with raw addresses using the

	/v/v/v/v/cycles syntax in the following order:

	FROM/TO/EVENT/INTX/ABORT/CYCLES/TYPE/SPEC syntax in the following order:

	FROM  : branch source instruction

	TO    : branch target instruction

        M/P/-: M=branch target mispredicted or branch direction was mispredicted, P=target predicted or direction predicted, -=not supported

	X/- : X=branch inside a transactional region, -=not in transaction region or not supported

	A/- : A=TSX abort entry, -=not aborted region or not supported

	cycles

	EVENT : M=branch target or direction was mispredicted

	        P=branch target or direction was predicted

	        N=branch not-taken

	        -=no event or not supported

	INTX  : X=branch inside a transactional region

	        -=branch not in transaction region or not supported

	ABORT : A=TSX abort entry

	        -=not aborted region or not supported

	CYCLES: the number of cycles that have elapsed since the last branch was recorded

	TYPE  : branch type: COND/UNCOND/IND/CALL/IND_CALL/RET etc.

	        -=not supported

	SPEC  : branch speculation info: SPEC_WRONG_PATH/NON_SPEC_CORRECT_PATH/SPEC_CORRECT_PATH

	        -=not supported



	The brstacksym is identical to brstack, except that the FROM and TO addresses are printed in a symbolic form if possible.