[5/5] docs: coresight: Document snapshot mode
diff mbox series

Message ID 20190501175052.29667-6-mathieu.poirier@linaro.org
State New
Headers show
Series
  • coresight: Fix snapshot mode
Related show

Commit Message

Mathieu Poirier May 1, 2019, 5:50 p.m. UTC
Because of the resctriction imposed by the internal memory buffer
of some CoreSight sink, using the framework in snapshot mode can
be a little trickly.  As such document the process to make user
experience more enjoyable.

Signed-off-by: Mathieu Poirier <mathieu.poirier@linaro.org>
---
 Documentation/trace/coresight.txt | 41 ++++++++++++++++++++++++++++++-
 1 file changed, 40 insertions(+), 1 deletion(-)

Comments

Leo Yan May 11, 2019, 7:32 a.m. UTC | #1
On Wed, May 01, 2019 at 11:50:52AM -0600, Mathieu Poirier wrote:

[...]

> +2.2) Snapshot mode:
> +
> +Using perf's built-in snapshot mode with CoreSight tracers is supported - to
> +do so the '-S' command line option needs to be specified.  Since current sink
> +devices are used in double-buffer mode when operated from the perf interface,
> +the size of the perf ring buffer needs to be adjusted to match the size of the
> +buffer used by the CoreSight sinks.  From the perf command line it is possible
> +to specify the number of pages to use for a session using the '-m,X' option,
> +where X is the amount of pages.
> +
> +The system memory buffer used by ETR devices is automatically adjusted
> +to match the size of the perf ring buffer and as such does not need to be
> +modified on the perf command line.  For ETB and ETF devices the perf ring
> +buffer size need to be adjusted to match the size of the internal buffer.
> +
> +The following examples assume a system page size of 4096 byte:
> +
> +	# cat /sys/bus/coresight/devices/20010000.etb/mgmt/rdp
> +	0x2000
> +	# perf record -e cs_etm/@20010000.etf/ -S -m,8 --per-thread $APP

In this case it shows the usage for etb, thus should:
s/20010000.etf/20010000.etb/

BTW, the user needs to convert the rdp to byte size with multiplying 4,
it's good to explain for this in the doc or give related info in the
driver warning log.

Thanks,
Leo Yan

> +	# cat /sys/bus/coresight/devices/20010000.etf/buffer_size
> +	0x10000
> +	# perf record -e cs_etm/@20010000.etf/ -S -m,16 --per-thread $APP
> +
> +	# perf record -e cs_etm/@20070000.etr/ -S --per-thread $APP
> +
> +Once an application is launched trace snapshot are collected by sending the
> +USR2 message to the process being monitored:
> +
> +	# perf record -e cs_etm/@20070000.etr/ -S --per-thread $APP &
> +	[1] 14808
> +	# kill -USR2 14808
> +	...
> +	...
> +	# kill -USR2 14808
> +	...
> +	...
> +	# kill 14808

> +
>  
>  How to use the STM module
>  -------------------------
> -- 
> 2.17.1
>
Suzuki K Poulose May 13, 2019, 8:37 a.m. UTC | #2
Hi,

On 11/05/2019 08:32, Leo Yan wrote:
> On Wed, May 01, 2019 at 11:50:52AM -0600, Mathieu Poirier wrote:
> 
> [...]
> 
>> +2.2) Snapshot mode:
>> +
>> +Using perf's built-in snapshot mode with CoreSight tracers is supported - to
>> +do so the '-S' command line option needs to be specified.  Since current sink
>> +devices are used in double-buffer mode when operated from the perf interface,
>> +the size of the perf ring buffer needs to be adjusted to match the size of the
>> +buffer used by the CoreSight sinks.  From the perf command line it is possible
>> +to specify the number of pages to use for a session using the '-m,X' option,
>> +where X is the amount of pages.
>> +
>> +The system memory buffer used by ETR devices is automatically adjusted
>> +to match the size of the perf ring buffer and as such does not need to be
>> +modified on the perf command line.  For ETB and ETF devices the perf ring
>> +buffer size need to be adjusted to match the size of the internal buffer.
>> +
>> +The following examples assume a system page size of 4096 byte:
>> +
>> +	# cat /sys/bus/coresight/devices/20010000.etb/mgmt/rdp
>> +	0x2000
>> +	# perf record -e cs_etm/@20010000.etf/ -S -m,8 --per-thread $APP
> 
> In this case it shows the usage for etb, thus should:
> s/20010000.etf/20010000.etb/
> 
> BTW, the user needs to convert the rdp to byte size with multiplying 4,
> it's good to explain for this in the doc or give related info in the
> driver warning log.

If at all we want to match the aux space size with that of the device buffer,
I recommend exposing this via a new "buf_pages" attribute under the sysfs to
help the user.

Cheers
Suzuki
Leo Yan May 13, 2019, 11:16 a.m. UTC | #3
Hi Suzuki,

On Mon, May 13, 2019 at 09:37:01AM +0100, Suzuki K Poulose wrote:
> Hi,
> 
> On 11/05/2019 08:32, Leo Yan wrote:
> > On Wed, May 01, 2019 at 11:50:52AM -0600, Mathieu Poirier wrote:
> > 
> > [...]
> > 
> > > +2.2) Snapshot mode:
> > > +
> > > +Using perf's built-in snapshot mode with CoreSight tracers is supported - to
> > > +do so the '-S' command line option needs to be specified.  Since current sink
> > > +devices are used in double-buffer mode when operated from the perf interface,
> > > +the size of the perf ring buffer needs to be adjusted to match the size of the
> > > +buffer used by the CoreSight sinks.  From the perf command line it is possible
> > > +to specify the number of pages to use for a session using the '-m,X' option,
> > > +where X is the amount of pages.
> > > +
> > > +The system memory buffer used by ETR devices is automatically adjusted
> > > +to match the size of the perf ring buffer and as such does not need to be
> > > +modified on the perf command line.  For ETB and ETF devices the perf ring
> > > +buffer size need to be adjusted to match the size of the internal buffer.
> > > +
> > > +The following examples assume a system page size of 4096 byte:
> > > +
> > > +	# cat /sys/bus/coresight/devices/20010000.etb/mgmt/rdp
> > > +	0x2000
> > > +	# perf record -e cs_etm/@20010000.etf/ -S -m,8 --per-thread $APP
> > 
> > In this case it shows the usage for etb, thus should:
> > s/20010000.etf/20010000.etb/
> > 
> > BTW, the user needs to convert the rdp to byte size with multiplying 4,
> > it's good to explain for this in the doc or give related info in the
> > driver warning log.
> 
> If at all we want to match the aux space size with that of the device buffer,
> I recommend exposing this via a new "buf_pages" attribute under the sysfs to
> help the user.

Agree, I also saw you suggested in another email.  Using "buf_pages"
is directive and consistent for different sink devices.

Thanks,
Leo Yan
Mathieu Poirier May 13, 2019, 8:01 p.m. UTC | #4
On Mon, 13 May 2019 at 05:16, Leo Yan <leo.yan@linaro.org> wrote:
>
> Hi Suzuki,
>
> On Mon, May 13, 2019 at 09:37:01AM +0100, Suzuki K Poulose wrote:
> > Hi,
> >
> > On 11/05/2019 08:32, Leo Yan wrote:
> > > On Wed, May 01, 2019 at 11:50:52AM -0600, Mathieu Poirier wrote:
> > >
> > > [...]
> > >
> > > > +2.2) Snapshot mode:
> > > > +
> > > > +Using perf's built-in snapshot mode with CoreSight tracers is supported - to
> > > > +do so the '-S' command line option needs to be specified.  Since current sink
> > > > +devices are used in double-buffer mode when operated from the perf interface,
> > > > +the size of the perf ring buffer needs to be adjusted to match the size of the
> > > > +buffer used by the CoreSight sinks.  From the perf command line it is possible
> > > > +to specify the number of pages to use for a session using the '-m,X' option,
> > > > +where X is the amount of pages.
> > > > +
> > > > +The system memory buffer used by ETR devices is automatically adjusted
> > > > +to match the size of the perf ring buffer and as such does not need to be
> > > > +modified on the perf command line.  For ETB and ETF devices the perf ring
> > > > +buffer size need to be adjusted to match the size of the internal buffer.
> > > > +
> > > > +The following examples assume a system page size of 4096 byte:
> > > > +
> > > > + # cat /sys/bus/coresight/devices/20010000.etb/mgmt/rdp
> > > > + 0x2000
> > > > + # perf record -e cs_etm/@20010000.etf/ -S -m,8 --per-thread $APP
> > >
> > > In this case it shows the usage for etb, thus should:
> > > s/20010000.etf/20010000.etb/
> > >
> > > BTW, the user needs to convert the rdp to byte size with multiplying 4,
> > > it's good to explain for this in the doc or give related info in the
> > > driver warning log.
> >
> > If at all we want to match the aux space size with that of the device buffer,
> > I recommend exposing this via a new "buf_pages" attribute under the sysfs to
> > help the user.
>
> Agree, I also saw you suggested in another email.  Using "buf_pages"
> is directive and consistent for different sink devices.

I've been thinking about this.  Both ETR and ETF have a 'buffer_size"
entry in sysfs and ETB does not.  The first thing I suggest is to add
a "buffer_size" entry to the ETB driver so that all sink devices look
the same.  From there enhance the current information carried by
"buffer_size" to include pages. For example:

$cat 20070000.etr/buffer_size
0x100000 0x100

$ cat 20010000.etf/buffer_size
0x10000 0x10

$ cat 20010000.etb/buffer_size
0x8000 0x8

That way we have the information we need without adding more entries
to sysfs - all we need to do is update the documentation (which we'd
have to do anyway).  Let me know what you think.

Mathieu


>
> Thanks,
> Leo Yan
Mathieu Poirier May 13, 2019, 8:12 p.m. UTC | #5
On Mon, 13 May 2019 at 14:01, Mathieu Poirier
<mathieu.poirier@linaro.org> wrote:
>
> On Mon, 13 May 2019 at 05:16, Leo Yan <leo.yan@linaro.org> wrote:
> >
> > Hi Suzuki,
> >
> > On Mon, May 13, 2019 at 09:37:01AM +0100, Suzuki K Poulose wrote:
> > > Hi,
> > >
> > > On 11/05/2019 08:32, Leo Yan wrote:
> > > > On Wed, May 01, 2019 at 11:50:52AM -0600, Mathieu Poirier wrote:
> > > >
> > > > [...]
> > > >
> > > > > +2.2) Snapshot mode:
> > > > > +
> > > > > +Using perf's built-in snapshot mode with CoreSight tracers is supported - to
> > > > > +do so the '-S' command line option needs to be specified.  Since current sink
> > > > > +devices are used in double-buffer mode when operated from the perf interface,
> > > > > +the size of the perf ring buffer needs to be adjusted to match the size of the
> > > > > +buffer used by the CoreSight sinks.  From the perf command line it is possible
> > > > > +to specify the number of pages to use for a session using the '-m,X' option,
> > > > > +where X is the amount of pages.
> > > > > +
> > > > > +The system memory buffer used by ETR devices is automatically adjusted
> > > > > +to match the size of the perf ring buffer and as such does not need to be
> > > > > +modified on the perf command line.  For ETB and ETF devices the perf ring
> > > > > +buffer size need to be adjusted to match the size of the internal buffer.
> > > > > +
> > > > > +The following examples assume a system page size of 4096 byte:
> > > > > +
> > > > > + # cat /sys/bus/coresight/devices/20010000.etb/mgmt/rdp
> > > > > + 0x2000
> > > > > + # perf record -e cs_etm/@20010000.etf/ -S -m,8 --per-thread $APP
> > > >
> > > > In this case it shows the usage for etb, thus should:
> > > > s/20010000.etf/20010000.etb/
> > > >
> > > > BTW, the user needs to convert the rdp to byte size with multiplying 4,
> > > > it's good to explain for this in the doc or give related info in the
> > > > driver warning log.
> > >
> > > If at all we want to match the aux space size with that of the device buffer,
> > > I recommend exposing this via a new "buf_pages" attribute under the sysfs to
> > > help the user.
> >
> > Agree, I also saw you suggested in another email.  Using "buf_pages"
> > is directive and consistent for different sink devices.
>
> I've been thinking about this.  Both ETR and ETF have a 'buffer_size"
> entry in sysfs and ETB does not.  The first thing I suggest is to add
> a "buffer_size" entry to the ETB driver so that all sink devices look
> the same.  From there enhance the current information carried by
> "buffer_size" to include pages. For example:
>
> $cat 20070000.etr/buffer_size
> 0x100000 0x100
>
> $ cat 20010000.etf/buffer_size
> 0x10000 0x10
>
> $ cat 20010000.etb/buffer_size
> 0x8000 0x8
>
> That way we have the information we need without adding more entries
> to sysfs - all we need to do is update the documentation (which we'd
> have to do anyway).  Let me know what you think.

What I did forget to mention is that my next revision of the feature
does not mandate to make the ring buffer match the size of the
internal buffer memories.  The above reply was in the context of
letting users know how to make the size of the buffers match should
they want to.  But so far I haven't found a use case where doing so
would be beneficial.

>
> Mathieu
>
>
> >
> > Thanks,
> > Leo Yan

Patch
diff mbox series

diff --git a/Documentation/trace/coresight.txt b/Documentation/trace/coresight.txt
index efbc832146e7..6c602ae379e2 100644
--- a/Documentation/trace/coresight.txt
+++ b/Documentation/trace/coresight.txt
@@ -363,7 +363,6 @@  The --itrace option controls the type and frequency of synthesized events
 Note that only 64-bit programs are currently supported - further work is
 required to support instruction decode of 32-bit Arm programs.
 
-
 Generating coverage files for Feedback Directed Optimization: AutoFDO
 ---------------------------------------------------------------------
 
@@ -394,6 +393,46 @@  sort example is from the AutoFDO tutorial (https://gcc.gnu.org/wiki/AutoFDO/Tuto
 	Bubble sorting array of 30000 elements
 	5806 ms
 
+2.2) Snapshot mode:
+
+Using perf's built-in snapshot mode with CoreSight tracers is supported - to
+do so the '-S' command line option needs to be specified.  Since current sink
+devices are used in double-buffer mode when operated from the perf interface,
+the size of the perf ring buffer needs to be adjusted to match the size of the
+buffer used by the CoreSight sinks.  From the perf command line it is possible
+to specify the number of pages to use for a session using the '-m,X' option,
+where X is the amount of pages.
+
+The system memory buffer used by ETR devices is automatically adjusted
+to match the size of the perf ring buffer and as such does not need to be
+modified on the perf command line.  For ETB and ETF devices the perf ring
+buffer size need to be adjusted to match the size of the internal buffer.
+
+The following examples assume a system page size of 4096 byte:
+
+	# cat /sys/bus/coresight/devices/20010000.etb/mgmt/rdp
+	0x2000
+	# perf record -e cs_etm/@20010000.etf/ -S -m,8 --per-thread $APP
+
+	# cat /sys/bus/coresight/devices/20010000.etf/buffer_size
+	0x10000
+	# perf record -e cs_etm/@20010000.etf/ -S -m,16 --per-thread $APP
+
+	# perf record -e cs_etm/@20070000.etr/ -S --per-thread $APP
+
+Once an application is launched trace snapshot are collected by sending the
+USR2 message to the process being monitored:
+
+	# perf record -e cs_etm/@20070000.etr/ -S --per-thread $APP &
+	[1] 14808
+	# kill -USR2 14808
+	...
+	...
+	# kill -USR2 14808
+	...
+	...
+	# kill 14808
+
 
 How to use the STM module
 -------------------------