* perf/Documentation/ABI -- add some documentation for perf_event sysfs usage
@ 2013-07-03 19:39 Vince Weaver
2013-07-04 3:14 ` Vince Weaver
0 siblings, 1 reply; 6+ messages in thread
From: Vince Weaver @ 2013-07-03 19:39 UTC (permalink / raw)
To: linux-kernel
Cc: Jiri Olsa, Peter Zijlstra, Paul Mackerras, Ingo Molnar,
Arnaldo Carvalho de Melo, Stephane Eranian, Greg Kroah-Hartman
Add some documentation for the perf_event related
/sys/bus/event_source/bus/devices/
files, since in theory it's a stable interface and the only
current documentation is some lex and yacc files in the
perf tools directory.
Signed-off-by: Vince Weaver <vincent.weaver@maine.edu>
diff --git a/Documentation/ABI/stable/sysfs-bus-event_source-devices b/Documentation/ABI/stable/sysfs-bus-event_source-devices
new file mode 100644
index 0000000..9ef862f
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-bus-event_source-devices
@@ -0,0 +1,39 @@
+What: /sys/bus/event_source/bus/devices/*/events/*
+Date: Oct 2012
+KernelVersion: 3.8
+Contact: Jiri Olsa <jolsa@redhat.com>
+Description:
+ Each file in /sys/bus/event_source/bus/devices/*/events/
+ represents a predefined perf_event event.
+
+ The contents of the file are a string describing
+ fields to set when generating raw events for
+ the perf_event_open() system call.
+
+ The layout of the file is
+ attr=value[,attr=value]...
+ Where attr is the name of a bitfield described
+ in /sys/bus/event_source/bus/devices/*/format/*
+ and value is either a hex (starting with 0x) or decimal
+ value.
+
+
+What: /sys/bus/event_source/bus/devices/*/format/*
+Date: Oct 2012
+KernelVersion: 3.8
+Contact: Jiri Olsa <jolsa@redhat.com>
+Description:
+ Each file in /sys/bus/event_source/bus/devices/*/format/
+ represents a description of a bitfield used when
+ constructing raw perf_event_open() raw events.
+
+ The contents of the file are a string describing
+ the name of the field and its range.
+
+ The layout of the file is
+ field:low[-high]
+ Where field is the field name, low is the low bit
+ of the range, and the optional high value is the high
+ bit of the range. The low and high values are base-10
+ integers.
+
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: perf/Documentation/ABI -- add some documentation for perf_event sysfs usage
2013-07-03 19:39 perf/Documentation/ABI -- add some documentation for perf_event sysfs usage Vince Weaver
@ 2013-07-04 3:14 ` Vince Weaver
2013-07-04 9:02 ` Peter Zijlstra
0 siblings, 1 reply; 6+ messages in thread
From: Vince Weaver @ 2013-07-04 3:14 UTC (permalink / raw)
To: Vince Weaver
Cc: linux-kernel, Jiri Olsa, Peter Zijlstra, Paul Mackerras,
Ingo Molnar, Arnaldo Carvalho de Melo, Stephane Eranian,
Greg Kroah-Hartman, Andi Kleen
On Wed, 3 Jul 2013, Vince Weaver wrote:
>
> Add some documentation for the perf_event related
> /sys/bus/event_source/bus/devices/
> files, since in theory it's a stable interface and the only
> current documentation is some lex and yacc files in the
> perf tools directory.
OK, don't I feel silly, these values were already documented in
Documentation/ABI/testing/sysfs-bus-event_source-devices-events
rather than ABI/stable
To be fair I missed it because the documentation seemed to come from the
Power developers and not through perf_event
anyway, that documentation says the values will be hex only, which was
broken by
commit f9134f36aed59ab55c0ab1a4618dd455f15aef5f
Author: Andi Kleen <ak@linux.intel.com>
Date: Mon Jun 17 17:36:52 2013 -0700
perf/x86/intel: Add mem-loads/stores support for Haswell
which added:
EVENT_ATTR_STR(mem-loads, mem_ld_hsw, "event=0xcd,umask=0x1,ldlat=3");
(note ldlat is not in hex).
This broke the trinity fuzzer (which scans to look for events to use)
as well as some of my personal tools.
Should the ldlat value be fixed to be hex? Or should we ammend the ABI
document to allow decimal?
Vince
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: perf/Documentation/ABI -- add some documentation for perf_event sysfs usage
2013-07-04 3:14 ` Vince Weaver
@ 2013-07-04 9:02 ` Peter Zijlstra
2013-07-04 22:02 ` Jiri Olsa
0 siblings, 1 reply; 6+ messages in thread
From: Peter Zijlstra @ 2013-07-04 9:02 UTC (permalink / raw)
To: Vince Weaver
Cc: linux-kernel, Jiri Olsa, Paul Mackerras, Ingo Molnar,
Arnaldo Carvalho de Melo, Stephane Eranian, Greg Kroah-Hartman,
Andi Kleen
On Wed, Jul 03, 2013 at 11:14:40PM -0400, Vince Weaver wrote:
> On Wed, 3 Jul 2013, Vince Weaver wrote:
> OK, don't I feel silly, these values were already documented in
> Documentation/ABI/testing/sysfs-bus-event_source-devices-events
> rather than ABI/stable
>
> To be fair I missed it because the documentation seemed to come from the
> Power developers and not through perf_event
>
> anyway, that documentation says the values will be hex only, which was
> broken by
>
> commit f9134f36aed59ab55c0ab1a4618dd455f15aef5f
> Author: Andi Kleen <ak@linux.intel.com>
> Date: Mon Jun 17 17:36:52 2013 -0700
>
> perf/x86/intel: Add mem-loads/stores support for Haswell
>
>
> which added:
> EVENT_ATTR_STR(mem-loads, mem_ld_hsw, "event=0xcd,umask=0x1,ldlat=3");
>
> (note ldlat is not in hex).
>
> This broke the trinity fuzzer (which scans to look for events to use)
> as well as some of my personal tools.
>
> Should the ldlat value be fixed to be hex? Or should we ammend the ABI
> document to allow decimal?
I don't see a good reason not to allow decimal as well. Jolsa?
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: perf/Documentation/ABI -- add some documentation for perf_event sysfs usage
2013-07-04 9:02 ` Peter Zijlstra
@ 2013-07-04 22:02 ` Jiri Olsa
2013-07-05 15:28 ` Vince Weaver
0 siblings, 1 reply; 6+ messages in thread
From: Jiri Olsa @ 2013-07-04 22:02 UTC (permalink / raw)
To: Peter Zijlstra
Cc: Vince Weaver, linux-kernel, Paul Mackerras, Ingo Molnar,
Arnaldo Carvalho de Melo, Stephane Eranian, Greg Kroah-Hartman,
Andi Kleen
On Thu, Jul 04, 2013 at 11:02:53AM +0200, Peter Zijlstra wrote:
> On Wed, Jul 03, 2013 at 11:14:40PM -0400, Vince Weaver wrote:
> > On Wed, 3 Jul 2013, Vince Weaver wrote:
>
> > OK, don't I feel silly, these values were already documented in
> > Documentation/ABI/testing/sysfs-bus-event_source-devices-events
> > rather than ABI/stable
> >
> > To be fair I missed it because the documentation seemed to come from the
> > Power developers and not through perf_event
> >
> > anyway, that documentation says the values will be hex only, which was
> > broken by
> >
> > commit f9134f36aed59ab55c0ab1a4618dd455f15aef5f
> > Author: Andi Kleen <ak@linux.intel.com>
> > Date: Mon Jun 17 17:36:52 2013 -0700
> >
> > perf/x86/intel: Add mem-loads/stores support for Haswell
> >
> >
> > which added:
> > EVENT_ATTR_STR(mem-loads, mem_ld_hsw, "event=0xcd,umask=0x1,ldlat=3");
> >
> > (note ldlat is not in hex).
> >
> > This broke the trinity fuzzer (which scans to look for events to use)
> > as well as some of my personal tools.
> >
> > Should the ldlat value be fixed to be hex? Or should we ammend the ABI
> > document to allow decimal?
>
> I don't see a good reason not to allow decimal as well. Jolsa?
yep, no technical problem with decimal
hum, the doc mentions 'event' term only, which IS hex only AFAICS ;-)
I think this docs should be updated and either describe all
allowed terms or be generic enough to cover all of them.
jirka
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: perf/Documentation/ABI -- add some documentation for perf_event sysfs usage
2013-07-04 22:02 ` Jiri Olsa
@ 2013-07-05 15:28 ` Vince Weaver
2013-07-07 14:56 ` Jiri Olsa
0 siblings, 1 reply; 6+ messages in thread
From: Vince Weaver @ 2013-07-05 15:28 UTC (permalink / raw)
To: Jiri Olsa
Cc: Peter Zijlstra, Vince Weaver, linux-kernel, Paul Mackerras,
Ingo Molnar, Arnaldo Carvalho de Melo, Stephane Eranian,
Greg Kroah-Hartman, Andi Kleen
On Fri, 5 Jul 2013, Jiri Olsa wrote:
> On Thu, Jul 04, 2013 at 11:02:53AM +0200, Peter Zijlstra wrote:
> > On Wed, Jul 03, 2013 at 11:14:40PM -0400, Vince Weaver wrote:
> > > Documentation/ABI/testing/sysfs-bus-event_source-devices-events
> > >
> > > Should the ldlat value be fixed to be hex? Or should we ammend the ABI
> > > document to allow decimal?
> >
> > I don't see a good reason not to allow decimal as well. Jolsa?
>
> yep, no technical problem with decimal
>
> hum, the doc mentions 'event' term only, which IS hex only AFAICS ;-)
>
> I think this docs should be updated and either describe all
> allowed terms or be generic enough to cover all of them.
So you're saying the official kernel ABI should be "whatever the
userspace perf tool happens to accept"?
That's not really useful, especially as perf doesn't distinguish between
event strings read from sysfs and those passed on the perf command line.
The ABI documentation in effect ends up being a pointer to a mostly
incomprehensible lex/yacc file.
I think we should just remove the
Documentation/ABI/testing/sysfs-bus-event_source-devices-events
file as it's misleading. Userspace broke and no one cares.
It's not even easy to audit all places in the kernel that create the sysfs
event files because each architecture does it differently. And there's no
sane way to unit test this on a new kernel release because the values
printed depend on the hardware you have, so without a full range of all
families of cpus for all architectures you never know when someone has
added a decimal value, or started depending on { characters, etc.
This is the problem with perf in the tools directory, any other user of
the ABI is eternally second-class.
Vince
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: perf/Documentation/ABI -- add some documentation for perf_event sysfs usage
2013-07-05 15:28 ` Vince Weaver
@ 2013-07-07 14:56 ` Jiri Olsa
0 siblings, 0 replies; 6+ messages in thread
From: Jiri Olsa @ 2013-07-07 14:56 UTC (permalink / raw)
To: Vince Weaver
Cc: Peter Zijlstra, linux-kernel, Paul Mackerras, Ingo Molnar,
Arnaldo Carvalho de Melo, Stephane Eranian, Greg Kroah-Hartman,
Andi Kleen
On Fri, Jul 05, 2013 at 11:28:08AM -0400, Vince Weaver wrote:
> On Fri, 5 Jul 2013, Jiri Olsa wrote:
>
> > On Thu, Jul 04, 2013 at 11:02:53AM +0200, Peter Zijlstra wrote:
> > > On Wed, Jul 03, 2013 at 11:14:40PM -0400, Vince Weaver wrote:
>
> > > > Documentation/ABI/testing/sysfs-bus-event_source-devices-events
> > > >
> > > > Should the ldlat value be fixed to be hex? Or should we ammend the ABI
> > > > document to allow decimal?
> > >
> > > I don't see a good reason not to allow decimal as well. Jolsa?
> >
> > yep, no technical problem with decimal
> >
> > hum, the doc mentions 'event' term only, which IS hex only AFAICS ;-)
> >
> > I think this docs should be updated and either describe all
> > allowed terms or be generic enough to cover all of them.
>
> So you're saying the official kernel ABI should be "whatever the
> userspace perf tool happens to accept"?
nope, I meant whatever term is used by kernel to describe the event
'event, umask, edge, pc, any, inv, cmask, ldat'
please check x86_event_sysfs_show function
>
> That's not really useful, especially as perf doesn't distinguish between
> event strings read from sysfs and those passed on the perf command line.
> The ABI documentation in effect ends up being a pointer to a mostly
> incomprehensible lex/yacc file.
the documentation is missing, no argument here :-\
'sysfs-bus-event_source-devices-events' could be more descriptive
>
> I think we should just remove the
> Documentation/ABI/testing/sysfs-bus-event_source-devices-events
> file as it's misleading. Userspace broke and no one cares.
>
> It's not even easy to audit all places in the kernel that create the sysfs
> event files because each architecture does it differently. And there's no
> sane way to unit test this on a new kernel release because the values
> printed depend on the hardware you have, so without a full range of all
> families of cpus for all architectures you never know when someone has
> added a decimal value, or started depending on { characters, etc.
>
> This is the problem with perf in the tools directory, any other user of
> the ABI is eternally second-class.
with updated documentation I dont see the issue
jirka
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2013-07-07 14:56 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2013-07-03 19:39 perf/Documentation/ABI -- add some documentation for perf_event sysfs usage Vince Weaver
2013-07-04 3:14 ` Vince Weaver
2013-07-04 9:02 ` Peter Zijlstra
2013-07-04 22:02 ` Jiri Olsa
2013-07-05 15:28 ` Vince Weaver
2013-07-07 14:56 ` Jiri Olsa
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
all inboxes | Powered by JetHome®