perf_event_open() -- improve PERF_SAMPLE_BRANCH_STACK documentation

perf_event_open() -- improve PERF_SAMPLE_BRANCH_STACK documentation

[Vince Weaver]

Signed-off-by: Vince Weaver <vincent.weaver-e7X0jjDqjFGHXe+LvDLADg@public.gmane.org>

diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2
index 504e801..1fc4e27 100644
--- a/man2/perf_event_open.2
+++ b/man2/perf_event_open.2
@@ -654,8 +654,13 @@ Records additional data, if applicable.
 Usually returned by tracepoint events.
 .TP
 .BR PERF_SAMPLE_BRANCH_STACK " (Since Linux 3.4)"
-Records the branch stack.
-See branch_sample_type.
+This provides a record of recent branches, as provided
+by CPU branch sampling hardware (such as Intel Last Branch Record).
+Not all hardware supports this feature.
+
+See the
+.I branch_sample_type
+field for how to filter which branches are reported.
 .TP
 .BR PERF_SAMPLE_REGS_USER " (Since Linux 3.7)"
 Records the current user-level CPU register state
@@ -960,8 +965,17 @@ is a further extension of the
 field.
 .TP
 .IR "branch_sample_type" " (Since Linux 3.4)"
-This is used with the CPUs hardware branch sampling, if available.
-It can have one of the following values:
+If 
+.B PERF_SAMPLE_BRANCH_STACK
+is enabled, then this specifies what branches to include
+in the branch record.
+If the user does not set privilege level explicitly, the kernel
+will use the event's privilege level.
+Event and branch privilege levels do not have to match.
+The value is formed by ORing together zero or more of the following values,
+although 
+.B PERF_SAMPLE_BRANCH_ANY
+covers all branch types.
 .RS
 .TP
 .B PERF_SAMPLE_BRANCH_USER
@@ -1545,9 +1559,31 @@ is enabled, then a 64-bit value indicating
 the number of records is included, followed by
 .I bnr
 .I perf_branch_entry
-structures.
-These structures have from, to, and flags values indicating
-the from and to addresses from the branches on the callstack.
+structures which each include the fields:
+.RS
+.TP
+.I from
+indicating the source instruction (may not be a branch)
+.TP
+.I to
+the branch target
+.TP
+.I mispred
+the branch target was mispredicted
+.TP
+.I predicted
+the branch target was predicted.
+.RE
+The entries are from most to least recent, so the first entry
+has the most recent branch.
+
+Support for 
+.I mispred 
+and 
+.I predicted 
+is optional; if not supported both
+values will be 0.
+
 .TP
 .IR abi ", " regs[weight(mask)]
 If
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: perf_event_open() -- improve PERF_SAMPLE_BRANCH_STACK documentation

[Michael Kerrisk]

On 07/08/13 21:47, Vince Weaver wrote:
> 
> Signed-off-by: Vince Weaver <vincent.weaver-e7X0jjDqjFGHXe+LvDLADg@public.gmane.org>


Thanks. Applied!

Cheers,

Michael


> diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2
> index 504e801..1fc4e27 100644
> --- a/man2/perf_event_open.2
> +++ b/man2/perf_event_open.2
> @@ -654,8 +654,13 @@ Records additional data, if applicable.
>  Usually returned by tracepoint events.
>  .TP
>  .BR PERF_SAMPLE_BRANCH_STACK " (Since Linux 3.4)"
> -Records the branch stack.
> -See branch_sample_type.
> +This provides a record of recent branches, as provided
> +by CPU branch sampling hardware (such as Intel Last Branch Record).
> +Not all hardware supports this feature.
> +
> +See the
> +.I branch_sample_type
> +field for how to filter which branches are reported.
>  .TP
>  .BR PERF_SAMPLE_REGS_USER " (Since Linux 3.7)"
>  Records the current user-level CPU register state
> @@ -960,8 +965,17 @@ is a further extension of the
>  field.
>  .TP
>  .IR "branch_sample_type" " (Since Linux 3.4)"
> -This is used with the CPUs hardware branch sampling, if available.
> -It can have one of the following values:
> +If 
> +.B PERF_SAMPLE_BRANCH_STACK
> +is enabled, then this specifies what branches to include
> +in the branch record.
> +If the user does not set privilege level explicitly, the kernel
> +will use the event's privilege level.
> +Event and branch privilege levels do not have to match.
> +The value is formed by ORing together zero or more of the following values,
> +although 
> +.B PERF_SAMPLE_BRANCH_ANY
> +covers all branch types.
>  .RS
>  .TP
>  .B PERF_SAMPLE_BRANCH_USER
> @@ -1545,9 +1559,31 @@ is enabled, then a 64-bit value indicating
>  the number of records is included, followed by
>  .I bnr
>  .I perf_branch_entry
> -structures.
> -These structures have from, to, and flags values indicating
> -the from and to addresses from the branches on the callstack.
> +structures which each include the fields:
> +.RS
> +.TP
> +.I from
> +indicating the source instruction (may not be a branch)
> +.TP
> +.I to
> +the branch target
> +.TP
> +.I mispred
> +the branch target was mispredicted
> +.TP
> +.I predicted
> +the branch target was predicted.
> +.RE
> +The entries are from most to least recent, so the first entry
> +has the most recent branch.
> +
> +Support for 
> +.I mispred 
> +and 
> +.I predicted 
> +is optional; if not supported both
> +values will be 0.
> +
>  .TP
>  .IR abi ", " regs[weight(mask)]
>  If
> 

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html