Difference between revisions of "Linux CoreSight overview"

[quality revision] [pending revision]
(Created page with "<noinclude> {{ArticleBasedOnModel|Framework overview article model}} {{ArticleMainWriter|ChristopheR}} {{ArticleApprovedVersion | Jean-ChristopheT | Nobody | No previous a...")
m
 
Template:ArticleMainWriter Template:ArticleApprovedVersion
Under construction.png Coming soon

This article explains how the Arm®CoreSight framework is embedded in Linux kernel, how to configure it, and how to use it with Linux tools.

1 Framework purpose[edit]

Arm®CoreSight framework is used to monitor CoreSight devices. Its purpose is to collect and gather data, allowing to trace and debug an execution flow. It implements tools to control and configure all the CoreSight architecture on a given platform. In order to use this framework, the platform must embed CoreSight components on a hardware level. This framework provides tools to collect binary datas and decode them and is integrated in the perf utility.
Perf is a powerful performance analysis subsystem to monitor events occurring on a hardware level and on a software level as well.
The classic use of it is to sample events and record them in a file. This utility runs a command and gathers data into a file, perf.data, that can be inspected later on. This file is generated in the directory where the command was executed.
CoreSight can be used in many different use cases, as mentioned in How to trace with CoreSight section.

2 System overview[edit]

2.1 Component description[edit]

From User space to hardware

  • sysfs (User space)

This is the file system used to configure manually and interact with the components of the Kernel Space.

  • perf (User space)

The set of utilities available to trace and debug with CoreSight framework. [1] This is the main user interface to collect data and decode them with a human readable format.

  • Perf core (Kernel space)

The perf core [2] is a framework within the kernel to handle interactions with events and registers [3].

  • CoreSight Drivers (Kernel space)

These are the different drivers use by the framework. Each driver manage dedicated peripherals.[4]
It includes the following drivers : - "coresight-etm3x" [5] - "coresight-tmc-etf" [6]

  • CoreSight internal peripherals

This is the hardware layer, composed of all the components allowing to trace and debug. For further information about internal peripherals, please refer to : Arm CoreSight peripherals

  • Trace port (Hardware)

This port outputs the trace stream in real time on a Trace port.

3 Configuration[edit]

The objective of this chapter is to explain how to configure the Linux kernel and device tree to have the CoreSight framework activated, but also how to compile and configure libraries and tools used to trace and decode CoreSight data.

3.1 On target[edit]

3.1.1 Kernel configuration[edit]

The CoreSight feature is activated by default in ST deliveries. Nevertheless, if a specific configuration is required, Linux menuconfig tool can be used: Menuconfig or how to configure kernel and select:

For CoreSight features:


 [*] Device Drivers                                                                                                                                  
    [*] HW tracing support
        [*] STM (System Trace Module devices)
          [*]  Kernel console over STM devices                                                                         
          [*]  Copy the output from kernel Ftrace to STM engine  
 [*] Kernel hacking
    [*] CoreSight Tracing Support                                                                                  
        [*] CoreSight Link and Sink drivers                                                                          
          [*]  CoreSight generic TMC driver                                                                          
          [*]  CoreSight generic TPIU driver                                                                        
          [*]  CoreSight ETBv1.0 driver                                                                             
        [*]   CoreSight Embedded Trace Macrocell 3.x driver                                                          
        [*]   CoreSight System Trace Macrocell driver                                                                

Moreover CPUIDLE should be deactivated :


 [*] CPU Power Management 
    [*] CPU Idle
        [*] CPU idle PM support (CPU_IDLE=y)
          [*]  ARM CPU Idle Drivers
            [ ]  Generic ARM/ARM64 CPU idle Driver (ARM_CPUIDLE=n)

3.1.2 Device tree configuration[edit]

DT bindings documentation deals with all required or optional device tree properties.

Detailed DT configuration for STM32 internal peripherals: CoreSight device tree configuration.

3.1.3 OpenCSD and perf compilation[edit]

OpenCSD is an API providing resources to decode Arm CoreSight traces.

Once the kernel options activate the hardware internal peripherals, perf tools as well as the libraries allowing to decode CoreSight traces must be compiled and installed on the target.

Some variables need to be changed and set since the principal Makefile is broken and override environment variables of the SDK. As a turnaround, the CPPFLAGS and LDFLAGS have to be set as follow :

 PC $> export CPPFLAGS=$(echo $CPP | cut -d" " -f3-) && echo $CPPFLAGS
-mthumb -mfpu=neon-vfpv4 -mfloat-abi=hard -mcpu=cortex-a7 --sysroot=/local/home/gallaisr/STM32MPU_workspace/STM32MP15-Ecosystem-v1.2.0/Developer-Package/SDK/sysroots/cortexa7t2hf-neon-vfpv4-ostl-linux-gnueabi
 PC $> export LDFLAGS="$LDFLAGS $KFLAGS" && echo $LDFLAGS
-Wl,-O1 -Wl,--hash-style=gnu -Wl,--as-needed

This step will let the SDK compile normally the OpenCSD library. To compile the library, please follow this procedure: OpenCSD compilation.

3.2 On host[edit]

Decoding traces on a host computer is possible provided that perf built with OpenCSD library is installed on the system.

On Ubuntu 18.04 or newer, please refer to the following procedure : Off target OpenCSD compilation

Then, perf must be built as described on the following : Off target perf compilation

4 How to trace with CoreSight[edit]

Below examples were made to trace system calls and kernel symbols interactions made by the printf function in a hello_world program.

4.1 How to trace with CoreSight through sysfs interface[edit]

Trace collection using sysfs interface is recommended for experienced users with knowledge about CoreSight hardware and operating.

For further informations on how to trace using the sysfs interface, please see : coresight.rst

4.2 How to trace with CoreSight through perf utility[edit]

perf record command line is a tool collecting statistics based on thread, cpu or process and samples them in a perf.data file.
perf utility measures events happening coming from different layers (hardware or software). Those events can be listed with perf list. Each event to be traced is represented by an event in the perf command line. To record CoreSight events, the option "-e cs_etm/@tmc_etf0/" is mandatory in order to trace with the CoreSight debug subsystem.

 Board $> perf record -e cs_etm/@tmc_etf0/ --all-cpus ./hello_world 
 Hello world !
 [ perf record: Woken up 1 times to write data ]
 Warning:
 AUX data lost 1 times out of 1!
 
 [ perf record: Captured and wrote 0.143 MB perf.data ]

The above command means to record every CoreSight events happening at a CPU-wide level of the program hello_world.

User or kernel space events can be specifically filtered, using u and k options. For example the following will limit traces to user space:

 Board $> perf record -e cs_etm/@tmc_etf0/u --all-cpus ./hello_world
 Hello world !
 [ perf record: Woken up 1 times to write data ]
 Warning:
 AUX data lost 1 times out of 1!
 
 [ perf record: Captured and wrote 0.142 MB perf.data ]

For further informations please refer to the perf manual.

4.3 How to decode traces with perf[edit]

perf report command allows to display and extract various amount of information recorded with perf record. To perform a data report, the command must be run where the perf.data was stored. It is by default stored on the location where the perf record was run. Otherwise, perf will search the file in the current folder. If it is not the case, "-i" file_location can be specified which file to input with "-i" option. A "$HOME/.debug" folder is also created during acquisition. It contains all the information concerning the binaries, shared libraries and symbols used by the profile.

For more information, please refer to perf Wiki and to the perf manpage.

4.3.1 On target[edit]

Since the perf.data file is created directly on the target, there is no need to retrieve the file. Raw datas can be displayed with --dump option. Perf will proceed in presenting all information and will dump CoreSight details. It is not recommended to use it unless for experienced user.

Board $> >$ perf report --dump

And the output look like this perf.data.

Otherwise, a formatted display can be performed with :

 Board $> >$ perf report --stdio

This command displays the resulting output

In the case where kernel space samples were recorded, the vmlinux kernel image needs to be passed to the command input in order to decode kernel symbols. The vmlinux must refer to the corresponding kernel used on the target. This is done with -k option.

4.3.2 On host[edit]

To do this procedure, perf with OpenCSD must be compiled and installed on the host computer. For further information, see : On host compilation section

Since the file is generated on the target, it must be retrieved before decoding.

 PC $> scp root@$TARGET_IP_ADDRESS:/path/to/perf.data /path/to/storage/

The perf report command can then used as described on the previous section.

5 How to monitor the framework[edit]

The below sections explain different way to verify if the framework has been activated and is operationnal.

5.1 How to monitor with dmesg[edit]

CoreSight framework print out info and error messages. Dmesg command logs this information, which can be useful to trace if the framework loaded properly at initialisation time :

Board $> dmesg | grep coresight                                                                        
 [    5.291731] coresight stm0: STM500 initialized
 [    5.295531] coresight etm0: ETM 3.5 initialized
 [    5.300428] coresight etm1: ETM 3.5 initialized

This command traces if the device drivers were instantiated correctly at boot time. In case those trace are not present in the dmesg output, this means the devices were not correctly initialized.

5.2 How to monitor through sysfs interface[edit]

Although it is not recommended to use sysfs entry, it can be used to browse CoreSight components and show up if the framework did registered them. In case those trace are not present in the output, this means the devices were not correctly initialized.

 Board $> /sys/bus/coresight# ls
devices  drivers  drivers_autoprobe  drivers_probe  uevent

 Board $> /sys/bus/coresight# ls devices/
etm0  etm1  funnel0  replicator0  stm0  tmc_etf0  tpiu0

6 Source code location[edit]

The source files are located inside the Linux kernel. OpenCSD source code can be found on GitHub.

7 References[edit]


<noinclude>

{{ArticleBasedOnModel|[[Framework overview article model]]}}
{{ArticleMainWriter|ChristopheR}}
{{ArticleApprovedVersion | Jean-ChristopheT | Nobody | No previous approved version | Automatic approval (article under construction) | 28Jan’19}}
[[This article explains how the Arm<sup>&reg;</sup>CoreSight<sup>&trade;</sup> framework is embedded in Linux kernel, how to configure it, and how to use it with Linux tools. 

== Framework purpose ==
Arm<sup>&reg;</sup>CoreSight<sup>&trade;</sup> framework is used to monitor CoreSight devices. Its purpose is to collect and gather data, allowing to trace and debug an execution flow. It implements tools to control and configure all the CoreSight architecture on a given platform. In order to use this framework, the platform must embed CoreSight components on a hardware level. This framework provides tools to collect binary datas and decode them and is integrated in the perf utility. <br />

Perf is a powerful performance analysis subsystem to monitor events occurring on a hardware level and on a software level as well. <br />

The classic use of it is to sample events and record them in a file. This utility runs a command and gathers data into a file, perf.data, that can be inspected later on. This file is generated in the directory where the command was executed.<br />

CoreSight can be used in many different use cases, as mentioned in [[#How to trace with CoreSight|How to trace with CoreSight ]] section.

==System overview==
[[File:Coresight_framework_overview.png|thumb|center|766px|alt=Alternate text|CoreSight overview]]

===Component description===
''From User space to hardware''
*'''sysfs''' (User space)
This is the file system used to configure manually and interact with the components of the Kernel Space.

*'''perf''' (User space)
The set of utilities available to trace and debug with CoreSight framework. <ref>[https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/perf], Perf tool</ref>

This is the main user interface to collect data and decode them with a human readable format.

*'''Perf core''' (Kernel space)
The perf core <ref>[https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/perf/arch/arm/util], Perf core</ref> is a framework within the kernel to handle interactions with events and registers <ref>[https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/include/linux/perf_event.h], Perf kernel event</ref>.

*'''CoreSight Drivers''' (Kernel space)
These are the different drivers use by the framework. Each driver manage dedicated peripherals.<ref>https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/drivers/hwtracing/coresight/, More information</ref><br />

It includes the following drivers : </br>

- "coresight-etm3x" <ref>https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/drivers/hwtracing/coresight/coresight-etm3x.c, ETMv3 driver</ref></br>

- "coresight-tmc-etf" <ref>https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/drivers/hwtracing/coresight/coresight-tmc-etf.c, ETF driver</ref></br>


*'''CoreSight internal peripherals'''
This is the hardware layer, composed of all the components allowing to trace and debug. </br>

For further information about internal peripherals, please refer to : [[Arm CoreSight peripherals]]

*'''Trace port''' (Hardware)
This port outputs the trace stream in real time on a Trace port.

==Configuration ==
The objective of this chapter is to explain how to configure the Linux kernel and device tree to have the CoreSight framework activated, but also how to compile and configure libraries and tools used to trace and decode CoreSight data.

===On target===
====Kernel configuration====
The CoreSight feature is activated by default in ST deliveries.
Nevertheless, if a specific configuration is required, Linux menuconfig tool can be used: [[Menuconfig or how to configure kernel | Menuconfig or how to configure kernel ]] and select:

For CoreSight features:<pre>

 [*] Device Drivers                                                                                                                                  
    [*] HW tracing support
        [*] STM (System Trace Module devices)
          [*]  Kernel console over STM devices                                                                         
          [*]  Copy the output from kernel Ftrace to STM engine  
 [*] Kernel hacking
    [*] CoreSight Tracing Support                                                                                  
        [*] CoreSight Link and Sink drivers                                                                          
          [*]  CoreSight generic TMC driver                                                                          
          [*]  CoreSight generic TPIU driver                                                                        
          [*]  CoreSight ETBv1.0 driver                                                                             
        [*]   CoreSight Embedded Trace Macrocell 3.x driver                                                          
        [*]   CoreSight System Trace Macrocell driver                                                                </pre>

Moreover CPUIDLE should be deactivated :<pre>

 [*] CPU Power Management 
    [*] CPU Idle
        [*] CPU idle PM support (CPU_IDLE=y)
          [*]  ARM CPU Idle Drivers
            [ ]  Generic ARM/ARM64 CPU idle Driver (ARM_CPUIDLE=n)</pre>


====Device tree configuration====
DT bindings documentation deals with all required or optional [[Device tree|device tree]] properties.

Detailed DT configuration for STM32 internal peripherals: [[CoreSight device tree configuration|CoreSight device tree configuration]].

====OpenCSD and perf compilation====
OpenCSD is an API providing resources to decode Arm CoreSight traces.

Once the kernel options activate the hardware internal peripherals, perf tools as well as the libraries allowing to decode CoreSight traces must be compiled and installed on the target.

Some variables need to be changed and set since the principal Makefile is broken and override environment variables of the SDK.
As a turnaround, the CPPFLAGS and LDFLAGS have to be set as follow :

  {{PC$}} export CPPFLAGS=$(echo $CPP | cut -d" " -f3-) && echo $CPPFLAGS
 -mthumb -mfpu=neon-vfpv4 -mfloat-abi=hard -mcpu=cortex-a7 --sysroot=/local/home/gallaisr/STM32MPU_workspace/STM32MP15-Ecosystem-v1.2.0/Developer-Package/SDK/sysroots/cortexa7t2hf-neon-vfpv4-ostl-linux-gnueabi
  {{PC$}} export LDFLAGS="$LDFLAGS $KFLAGS" && echo $LDFLAGS
 -Wl,-O1 -Wl,--hash-style=gnu -Wl,--as-needed

This step will let the SDK compile normally the OpenCSD library.
To compile the library, please follow this procedure: [https://github.com/Linaro/OpenCSD/blob/master/HOWTO.md#off-target-opencsd-compilation OpenCSD compilation].

===On host===
Decoding traces on a host computer is possible provided that perf built with OpenCSD library is installed on the system.

On Ubuntu 18.04 or newer, please refer to the following procedure : [https://github.com/Linaro/OpenCSD/blob/master/HOWTO.md#off-target-opencsd-compilation Off target OpenCSD compilation]

Then, perf must be built as described on the following : [https://github.com/Linaro/OpenCSD/blob/master/HOWTO.md#off-target-perf-tools-compilation Off target perf compilation]

==How to trace with CoreSight ==
Below examples were made to trace system calls and kernel symbols interactions made by the printf function in a '''hello_world''' program.

=== How to trace with CoreSight through sysfs interface ===
Trace collection using sysfs interface is recommended for experienced users with knowledge about CoreSight hardware and operating.

For further informations on how to trace using the sysfs interface, please see : [https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/Documentation/trace/coresight/coresight.rst coresight.rst]

=== How to trace with CoreSight through perf utility ===
'''perf record''' command line is a tool collecting statistics based on thread, cpu or process and samples them in a '''perf.data''' file. <br />

perf utility measures events happening coming from different layers (hardware or software). Those events can be listed with '''perf list'''. Each event to be traced is represented by an event in the perf command line. To record CoreSight events, the option "-e cs_etm/@tmc_etf0/" is mandatory in order to trace with the CoreSight debug subsystem.

  {{Board$}} perf record -e cs_etm/@tmc_etf0/ --all-cpus ./hello_world 
  Hello world !
  [ perf record: Woken up 1 times to write data ]
  Warning:
  AUX data lost 1 times out of 1!

  [ perf record: Captured and wrote 0.143 MB perf.data ]

The above command means to record every CoreSight events happening at a CPU-wide level of the program hello_world.

User or kernel space events can be specifically filtered, using u and k options. For example the following will limit traces to user space:

  {{Board$}} perf record -e cs_etm/@tmc_etf0/u --all-cpus ./hello_world
  Hello world !
  [ perf record: Woken up 1 times to write data ]
  Warning:
  AUX data lost 1 times out of 1!

  [ perf record: Captured and wrote 0.142 MB perf.data ]

For further informations please refer to the [[Perf | perf]] manual.

=== How to decode traces with perf ===

'''perf report''' command allows to display and extract various amount of information recorded with '''perf record'''.</br>

To perform a data report, the command must be run where the perf.data was stored. It is by default stored on the location where the '''perf record''' was run. Otherwise, perf will search the file in the current folder. If it is not the case, '''"-i" file_location''' can be specified which file to input with "-i" option.</br>

A "$HOME/.debug" folder is also created during acquisition. It contains all the information concerning the binaries, shared libraries and symbols used by the profile.</br>


For more information, please refer to [[perf|perf Wiki]] and to the [https://man7.org/linux/man-pages/man1/perf.1.html perf manpage].

==== On target ====
Since the perf.data file is created directly on the target, there is no need to retrieve the file.</br>

Raw datas can be displayed with '''--dump''' option. Perf will proceed in presenting all information and will dump CoreSight details. It is not recommended to use it unless for experienced user. </br>


 {{Board$}} >$ perf report --dump

And the output look like this [[File:perf.data.dump.txt|perf.data]].

Otherwise, a formatted display can be performed with :
  {{Board$}} >$ perf report --stdio

This command displays the resulting [[File:perf.data.stdio.txt|output]]

In the case where kernel space samples were recorded, the vmlinux kernel image needs to be passed to the command input in order to decode kernel symbols. The vmlinux must refer to the corresponding kernel used on the target. This is done with '''-k''' option.</br>


==== On host ====
To do this procedure, perf with OpenCSD must be compiled and installed on the host computer. For further information, see : [[#On host | On host compilation section]]

Since the file is generated on the target, it must be retrieved before decoding.
  {{PC$}} scp root@$TARGET_IP_ADDRESS:/path/to/perf.data /path/to/storage/

The '''perf report''' command can then used as described on the [[#On target|previous]] section.

==How to monitor the framework==
The below sections explain different way to verify if the framework has been activated and is operationnal.

=== How to monitor with dmesg ===
CoreSight  framework print out info and error messages. Dmesg command logs this information, which can be useful to trace if the framework loaded properly at initialisation time :

 {{Board$}} '''dmesg | grep coresight'''                                                                        
  [    5.291731] coresight stm0: STM500 initialized
  [    5.295531] coresight etm0: ETM 3.5 initialized
  [    5.300428] coresight etm1: ETM 3.5 initialized

This command traces if the device drivers were instantiated correctly at boot time. In case those trace are not present in the dmesg output, this means the devices were not correctly initialized.

=== How to monitor through sysfs interface ===

Although it is not recommended to use '''sysfs''' entry, it can be used to browse CoreSight components and show up if the framework did registered them. In case those trace are not present in the output, this means the devices were not correctly initialized.

  {{Board$}} /sys/bus/coresight# ls
 devices  drivers  drivers_autoprobe  drivers_probe  uevent

  {{Board$}} /sys/bus/coresight# ls devices/
 etm0  etm1  funnel0  replicator0  stm0  tmc_etf0  tpiu0

==Source code location==
The source files are located inside the Linux kernel.</br>

OpenCSD source code can be found on [https://github.com/Linaro/OpenCSD GitHub].

==References==<references />

<noinclude>

[[Category:Embedded trace and debug]]</noinclude>

{{UnderConstruction}}|1]]
{{ArticleBasedOnModel|Framework overview article model}}</noinclude>
(72 intermediate revisions by 5 users not shown)
Line 1: Line 1:
  +
This article explains how the Arm<sup>&reg;</sup>CoreSight<sup>&trade;</sup> framework is embedded in Linux kernel, how to configure it, and how to use it with Linux tools.
  +
  +
== Framework purpose ==
  +
Arm<sup>&reg;</sup>CoreSight<sup>&trade;</sup> framework is used to monitor CoreSight devices. Its purpose is to collect and gather data, allowing to trace and debug an execution flow. It implements tools to control and configure all the CoreSight architecture on a given platform. In order to use this framework, the platform must embed CoreSight components on a hardware level. This framework provides tools to collect binary datas and decode them and is integrated in the perf utility. <br />
  +
Perf is a powerful performance analysis subsystem to monitor events occurring on a hardware level and on a software level as well. <br />
  +
The classic use of it is to sample events and record them in a file. This utility runs a command and gathers data into a file, perf.data, that can be inspected later on. This file is generated in the directory where the command was executed.<br />
  +
CoreSight can be used in many different use cases, as mentioned in [[#How to trace with CoreSight|How to trace with CoreSight ]] section.
  +
  +
==System overview==
  +
[[File:Coresight_framework_overview.png|thumb|center|766px|alt=Alternate text|CoreSight overview]]
  +
  +
===Component description===
  +
''From User space to hardware''
  +
*'''sysfs''' (User space)
  +
This is the file system used to configure manually and interact with the components of the Kernel Space.
  +
  +
*'''perf''' (User space)
  +
The set of utilities available to trace and debug with CoreSight framework. <ref>[https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/perf], Perf tool</ref>
  +
This is the main user interface to collect data and decode them with a human readable format.
  +
  +
*'''Perf core''' (Kernel space)
  +
The perf core <ref>[https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/tools/perf/arch/arm/util], Perf core</ref> is a framework within the kernel to handle interactions with events and registers <ref>[https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/include/linux/perf_event.h], Perf kernel event</ref>.
  +
  +
*'''CoreSight Drivers''' (Kernel space)
  +
These are the different drivers use by the framework. Each driver manage dedicated peripherals.<ref>https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/drivers/hwtracing/coresight/, More information</ref><br />
  +
It includes the following drivers : </br>
  +
- "coresight-etm3x" <ref>https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/drivers/hwtracing/coresight/coresight-etm3x.c, ETMv3 driver</ref></br>
  +
- "coresight-tmc-etf" <ref>https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/drivers/hwtracing/coresight/coresight-tmc-etf.c, ETF driver</ref></br>
  +
  +
*'''CoreSight internal peripherals'''
  +
This is the hardware layer, composed of all the components allowing to trace and debug. </br>
  +
For further information about internal peripherals, please refer to : [[Arm CoreSight peripherals]]
  +
  +
*'''Trace port''' (Hardware)
  +
This port outputs the trace stream in real time on a Trace port.
  +
  +
==Configuration ==
  +
The objective of this chapter is to explain how to configure the Linux kernel and device tree to have the CoreSight framework activated, but also how to compile and configure libraries and tools used to trace and decode CoreSight data.
  +
  +
===On target===
  +
====Kernel configuration====
  +
The CoreSight feature is activated by default in ST deliveries.
  +
Nevertheless, if a specific configuration is required, Linux menuconfig tool can be used: [[Menuconfig or how to configure kernel | Menuconfig or how to configure kernel ]] and select:
  +
  +
For CoreSight features:
  +
<pre>
  +
[*] Device Drivers                                                                                                                                 
  +
    [*] HW tracing support
  +
        [*] STM (System Trace Module devices)
  +
          [*]  Kernel console over STM devices                                                                       
  +
          [*]  Copy the output from kernel Ftrace to STM engine 
  +
[*] Kernel hacking
  +
    [*] CoreSight Tracing Support                                                                                 
  +
        [*] CoreSight Link and Sink drivers                                                                         
  +
          [*]  CoreSight generic TMC driver                                                                         
  +
          [*]  CoreSight generic TPIU driver                                                                       
  +
          [*]  CoreSight ETBv1.0 driver                                                                           
  +
        [*]  CoreSight Embedded Trace Macrocell 3.x driver                                                         
  +
        [*]  CoreSight System Trace Macrocell driver                                                               
  +
</pre>
  +
Moreover CPUIDLE should be deactivated :
  +
<pre>
  +
[*] CPU Power Management
  +
    [*] CPU Idle
  +
        [*] CPU idle PM support (CPU_IDLE=y)
  +
          [*]  ARM CPU Idle Drivers
  +
            [ ]  Generic ARM/ARM64 CPU idle Driver (ARM_CPUIDLE=n)
  +
</pre>
  +
  +
====Device tree configuration====
  +
DT bindings documentation deals with all required or optional [[Device tree|device tree]] properties.
  +
  +
Detailed DT configuration for STM32 internal peripherals: [[CoreSight device tree configuration|CoreSight device tree configuration]].
  +
  +
====OpenCSD and perf compilation====
  +
OpenCSD is an API providing resources to decode Arm CoreSight traces.
  +
  +
Once the kernel options activate the hardware internal peripherals, perf tools as well as the libraries allowing to decode CoreSight traces must be compiled and installed on the target.
  +
  +
Some variables need to be changed and set since the principal Makefile is broken and override environment variables of the SDK.
  +
As a turnaround, the CPPFLAGS and LDFLAGS have to be set as follow :
  +
  +
  {{PC$}} export CPPFLAGS=$(echo $CPP | cut -d" " -f3-) && echo $CPPFLAGS
  +
-mthumb -mfpu=neon-vfpv4 -mfloat-abi=hard -mcpu=cortex-a7 --sysroot=/local/home/gallaisr/STM32MPU_workspace/STM32MP15-Ecosystem-v1.2.0/Developer-Package/SDK/sysroots/cortexa7t2hf-neon-vfpv4-ostl-linux-gnueabi
  +
  {{PC$}} export LDFLAGS="$LDFLAGS $KFLAGS" && echo $LDFLAGS
  +
-Wl,-O1 -Wl,--hash-style=gnu -Wl,--as-needed
  +
  +
This step will let the SDK compile normally the OpenCSD library.
  +
To compile the library, please follow this procedure: [https://github.com/Linaro/OpenCSD/blob/master/HOWTO.md#off-target-opencsd-compilation OpenCSD compilation].
  +
  +
===On host===
  +
Decoding traces on a host computer is possible provided that perf built with OpenCSD library is installed on the system.
  +
  +
On Ubuntu 18.04 or newer, please refer to the following procedure : [https://github.com/Linaro/OpenCSD/blob/master/HOWTO.md#off-target-opencsd-compilation Off target OpenCSD compilation]
  +
  +
Then, perf must be built as described on the following : [https://github.com/Linaro/OpenCSD/blob/master/HOWTO.md#off-target-perf-tools-compilation Off target perf compilation]
  +
  +
==How to trace with CoreSight ==
  +
Below examples were made to trace system calls and kernel symbols interactions made by the printf function in a '''hello_world''' program.
  +
  +
=== How to trace with CoreSight through sysfs interface ===
  +
Trace collection using sysfs interface is recommended for experienced users with knowledge about CoreSight hardware and operating.
  +
  +
For further informations on how to trace using the sysfs interface, please see : [https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/tree/Documentation/trace/coresight/coresight.rst coresight.rst]
  +
  +
=== How to trace with CoreSight through perf utility ===
  +
'''perf record''' command line is a tool collecting statistics based on thread, cpu or process and samples them in a '''perf.data''' file. <br />
  +
perf utility measures events happening coming from different layers (hardware or software). Those events can be listed with '''perf list'''. Each event to be traced is represented by an event in the perf command line. To record CoreSight events, the option "-e cs_etm/@tmc_etf0/" is mandatory in order to trace with the CoreSight debug subsystem.
  +
  +
  {{Board$}} perf record -e cs_etm/@tmc_etf0/ --all-cpus ./hello_world
  +
  Hello world !
  +
  [ perf record: Woken up 1 times to write data ]
  +
  Warning:
  +
  AUX data lost 1 times out of 1!
  +
 
  +
  [ perf record: Captured and wrote 0.143 MB perf.data ]
  +
  +
The above command means to record every CoreSight events happening at a CPU-wide level of the program hello_world.
  +
  +
User or kernel space events can be specifically filtered, using u and k options. For example the following will limit traces to user space:
  +
  +
  {{Board$}} perf record -e cs_etm/@tmc_etf0/u --all-cpus ./hello_world
  +
  Hello world !
  +
  [ perf record: Woken up 1 times to write data ]
  +
  Warning:
  +
  AUX data lost 1 times out of 1!
  +
 
  +
  [ perf record: Captured and wrote 0.142 MB perf.data ]
  +
  +
For further informations please refer to the [[Perf | perf]] manual.
  +
  +
=== How to decode traces with perf ===
  +
  +
'''perf report''' command allows to display and extract various amount of information recorded with '''perf record'''.</br>
  +
To perform a data report, the command must be run where the perf.data was stored. It is by default stored on the location where the '''perf record''' was run. Otherwise, perf will search the file in the current folder. If it is not the case, '''"-i" file_location''' can be specified which file to input with "-i" option.</br>
  +
A "$HOME/.debug" folder is also created during acquisition. It contains all the information concerning the binaries, shared libraries and symbols used by the profile.</br>
  +
  +
For more information, please refer to [[perf|perf Wiki]] and to the [https://man7.org/linux/man-pages/man1/perf.1.html perf manpage].
  +
  +
==== On target ====
  +
Since the perf.data file is created directly on the target, there is no need to retrieve the file.</br>
  +
Raw datas can be displayed with '''--dump''' option. Perf will proceed in presenting all information and will dump CoreSight details. It is not recommended to use it unless for experienced user. </br>
  +
  +
{{Board$}} >$ perf report --dump
  +
  +
And the output look like this [[File:perf.data.dump.txt|perf.data]].
  +
  +
Otherwise, a formatted display can be performed with :
  +
  {{Board$}} >$ perf report --stdio
  +
  +
This command displays the resulting [[File:perf.data.stdio.txt|output]]
  +
  +
In the case where kernel space samples were recorded, the vmlinux kernel image needs to be passed to the command input in order to decode kernel symbols. The vmlinux must refer to the corresponding kernel used on the target. This is done with '''-k''' option.</br>
  +
  +
==== On host ====
  +
To do this procedure, perf with OpenCSD must be compiled and installed on the host computer. For further information, see : [[#On host | On host compilation section]]
  +
  +
Since the file is generated on the target, it must be retrieved before decoding.
  +
  {{PC$}} scp root@$TARGET_IP_ADDRESS:/path/to/perf.data /path/to/storage/
  +
  +
The '''perf report''' command can then used as described on the [[#On target|previous]] section.
  +
  +
==How to monitor the framework==
  +
The below sections explain different way to verify if the framework has been activated and is operationnal.
  +
  +
=== How to monitor with dmesg ===
  +
CoreSight  framework print out info and error messages. Dmesg command logs this information, which can be useful to trace if the framework loaded properly at initialisation time :
  +
  +
{{Board$}} '''dmesg | grep coresight'''                                                                       
  +
  [    5.291731] coresight stm0: STM500 initialized
  +
  [    5.295531] coresight etm0: ETM 3.5 initialized
  +
  [    5.300428] coresight etm1: ETM 3.5 initialized
  +
  +
This command traces if the device drivers were instantiated correctly at boot time. In case those trace are not present in the dmesg output, this means the devices were not correctly initialized.
  +
  +
=== How to monitor through sysfs interface ===
  +
  +
Although it is not recommended to use '''sysfs''' entry, it can be used to browse CoreSight components and show up if the framework did registered them. In case those trace are not present in the output, this means the devices were not correctly initialized.
  +
  +
  {{Board$}} /sys/bus/coresight# ls
  +
devices  drivers  drivers_autoprobe  drivers_probe  uevent
  +
  +
  {{Board$}} /sys/bus/coresight# ls devices/
  +
etm0  etm1  funnel0  replicator0  stm0  tmc_etf0  tpiu0
  +
  +
==Source code location==
  +
The source files are located inside the Linux kernel.</br>
  +
OpenCSD source code can be found on [https://github.com/Linaro/OpenCSD GitHub].
  +
  +
==References==
  +
<references />
  +
 
<noinclude>
 
<noinclude>
{{ArticleBasedOnModel|[[Framework overview article model]]}}
+
[[Category:Embedded trace and debug|1]]
{{ArticleMainWriter|ChristopheR}}
+
{{ArticleBasedOnModel|Framework overview article model}}
{{ArticleApprovedVersion | Jean-ChristopheT | Nobody | No previous approved version | Automatic approval (article under construction) | 28Jan’19}}
 
[[Category:Embedded trace and debug]]
 
 
</noinclude>
 
</noinclude>
{{UnderConstruction}}