diff --git a/README_Streamline.txt b/README_Streamline.txt
--- a/README_Streamline.txt
+++ b/README_Streamline.txt
*** Purpose ***\r
\r
Instructions on setting up ARM Streamline on the target.\r
-The gator driver and gator daemon are required to run on the ARM linux target in order for ARM Streamline to operate.\r
+The gator driver and gator daemon are required to run on the ARM Linux target in order for ARM Streamline to operate. A new early access feature allows the gator daemon can run without the gator driver by using userspace APIs with reduced functionality when using Linux 3.12 or later.\r
The driver should be built as a module and the daemon must run with root permissions on the target.\r
\r
*** Introduction ***\r
\r
-A linux development environment with cross compiling tools is most likely required, depending on what is already created and provided.\r
+A Linux development environment with cross compiling tools is most likely required, depending on what is already created and provided.\r
-For users, the ideal environment is to be given a BSP with gatord and gator.ko already running on a properly configured kernel. In such a scenario, a development environment is not needed, root permission may or may not be needed (gatord must be executed with root permissions but can be automatically started, see below), and the user can run Streamline and profile the system without any setup.\r
-The ideal development environment has the kernel source code available to be rebuilt, usually by cross-compiling on a host machine. This environment allows the greatest flexibility in configuring the kernel and building the gator driver module.\r
-However, it is possible that a user/developer has a kernel but does not have the source code. In this scenario it may or may not be possible to obtain a valid profile.\r
-First, check if the kernel has the proper configuration options (see below). Profiling cannot occur using a kernel that is not configured properly, a new kernel must be created. See if /proc/config.gz exists on the target.\r
-Second, given a properly configured kernel, check if the filesystem contains the kernel source/headers, which can be used to re-create the gator driver. These files may be located in different areas, but common locations are /lib/modules/ and /usr/src.\r
-If the kernel is not properly configured or sources/headers are not available, the developer is on their own and kernel creation is beyond the scope of this document. Note: It is possible for a module to work when compiled against a similar kernel source code, though this is not guaranteed to work due to differences in kernel structures, exported symbols and incompatible configuration parameters.\r
+ -If the target is running Linux 3.12 or later the kernel driver is not required and userspace APIs will be used instead.\r
\r
*** Kernel configuration ***\r
\r
@@ -24,13 +25,12 @@ menuconfig options (depending on the kernel version, the location of these confi
- [*] Profiling Support (enables CONFIG_PROFILING)\r
- Kernel Features\r
- [*] High Resolution Timer Support (enables CONFIG_HIGH_RES_TIMERS)\r
- - [*] Use local timer interrupts (only required for SMP, enables CONFIG_LOCAL_TIMERS)\r
+ - [*] Use local timer interrupts (only required for SMP and for version before Linux 3.12, enables CONFIG_LOCAL_TIMERS)\r
- [*] Enable hardware performance counter support for perf events (enables CONFIG_HW_PERF_EVENTS)\r
- CPU Power Management\r
- CPU Frequency scaling\r
- [*] CPU Frequency scaling (enables CONFIG_CPU_FREQ)\r
- Kernel hacking\r
- - [*] Mutex debugging: basic checks (optional, enables CONFIG_DEBUG_MUTEXES)\r
- [*] Compile the kernel with debug info (optional, enables CONFIG_DEBUG_INFO)\r
- [*] Tracers\r
- [*] Trace process context switches and events (#)\r
CONFIG_HIGH_RES_TIMERS\r
CONFIG_LOCAL_TIMERS (for SMP systems)\r
CONFIG_PERF_EVENTS and CONFIG_HW_PERF_EVENTS (kernel versions 3.0 and greater)\r
-CONFIG_DEBUG_MUTEXES (optional, provides 'mutex' as a reason code when a thread stops running)\r
CONFIG_DEBUG_INFO (optional, used for analyzing the kernel)\r
CONFIG_CPU_FREQ (optional, provides frequency setting of the CPU)\r
\r
These may be verified on a running system using /proc/config.gz (if this file exists) by running 'zcat /proc/config.gz | grep <option>'. For example, confirming that CONFIG_PROFILING is enabled\r
- > zcat /proc/config.gz | grep CONFIG_PROFILING\r
- CONFIG_PROFILING=y\r
+ > zcat /proc/config.gz | grep CONFIG_PROFILING\r
+ CONFIG_PROFILING=y\r
+\r
+If a device tree is used it must include the pmu bindings, see Documentation/devicetree/bindings/arm/pmu.txt for details.\r
\r
*** Checking the gator requirements ***\r
\r
make -C /home/username/kernel_2.6.32/ M=`pwd` ARCH=arm CROSS_COMPILE=/home/username/gcc-linaro-arm-linux-gnueabihf-4.7-2013.01-20130125_linux/bin/arm-linux-gnueabihf- modules\r
If successful, a gator.ko module should be generated\r
\r
+It is also possible to integrate the gator.ko module into the kernel build system\r
+ cd /path/to/kernel/build/dir\r
+ cd drivers\r
+ mkdir gator\r
+ cp -r /path/to/gator/driver-src/* gator\r
+Edit Makefile in the kernel drivers folder and add this to the end\r
+ obj-$(CONFIG_GATOR) += gator/\r
+Edit Kconfig in the kernel drivers folder and add this before the last endmenu\r
+ source "drivers/gator/Kconfig"\r
+You can now select gator when using menuconfig while configuring the kernel and rebuild as directed\r
+\r
*** Building the gator daemon ***\r
\r
cd /path/to/gator/daemon-src\r
ndk-build\r
or execute /path/to/ndk/ndk-build if the ndk is not on your path\r
gatord should now be created and located in libs/armeabi\r
+ If you get an error like the following, upgrade to a more recent version of the android ndk\r
+ jni/PerfGroup.cpp: In function 'int sys_perf_event_open(perf_event_attr*, pid_t, int, int, long unsigned int)':\r
+ jni/PerfGroup.cpp:36:17: error: '__NR_perf_event_open' was not declared in this scope\r
\r
*** Running gator ***\r
\r
With root privileges, run the daemon\r
sudo ./gatord &\r
Note: gatord requires libstdc++.so.6 which is usually supplied by the Linux distribution on the target. A copy of libstdc++.so.6 is available in the DS-5 Linux example distribution.\r
+If gator.ko is not loaded and is not in the same directory as gatord when using Linux 3.12 or later, gatord can run without gator.ko by using userspace APIs. Not all features are supported by userspace gator. If /dev/gator/version does not exist after starting gatord it is running userspace gator.\r
\r
*** Customizing the l2c-310 Counter ***\r
\r
@@ -98,10 +114,14 @@ The l2c-310 counter in gator_events_l2c-310.c contains hard coded offsets where
Further, the l2c-310 counter can be disabled by providing an offset of zero, ex:\r
insmod gator.ko l2c310_addr=0\r
\r
+*** CCN-504 ***\r
+\r
+CCN-504 is disabled by default. To enable CCN-504, insmod gator module with the ccn504_addr=<addr> parameter where addr is the base address of the CCN-504 configuration register space (PERIPHBASE), ex: insmod gator.ko ccn504_addr=0x2E000000.\r
+\r
*** Compiling an application or shared library ***\r
\r
Recommended compiler settings:\r
- "-g": Debug symbols needed for best analysis results.\r
+ "-g": Debug information, such as line numbers, needed for best analysis results.\r
"-fno-inline": Speed improvement when processing the image files and most accurate analysis results.\r
"-fno-omit-frame-pointer": ARM EABI frame pointers (Code Sourcery cross compiler) allow recording of the call stack with each sample taken when in ARM state (i.e. not -mthumb).\r
"-marm": This option is required if your compiler is configured with --with-mode=thumb, otherwise call stack unwinding will not work.\r
@@ -115,18 +135,31 @@ Attempting to run an incompatible binary often results in the confusing error me
*** Bugs ***\r
\r
There is a bug in some Linux kernels where perf misidentifies the CPU type. To see if you are affected by this, run ls /sys/bus/event_source/devices/ and verify the listed processor type matches what is expected. For example, an A9 should show the following.\r
-\r
-# ls /sys/bus/event_source/devices/\r
-ARMv7_Cortex_A9 breakpoint software tracepoint\r
-\r
-To workaround the issue try upgrading to a later kernel or comment out the gator_events_perf_pmu_cpu_init(gator_cpu, type); cal in gator_events_perf_pmu.c\r
+ # ls /sys/bus/event_source/devices/\r
+ ARMv7_Cortex_A9 breakpoint software tracepoint\r
+To work around the issue try upgrading to a later kernel or comment out the gator_events_perf_pmu_cpu_init(gator_cpu, type); call in gator_events_perf_pmu.c\r
+\r
+There is a bug in some Linux kernels where an Oops may occurs when using userspace gator and a core is offlined. The fix was merged into mainline in 3.14-rc5, see http://git.kernel.org/tip/e3703f8cdfcf39c25c4338c3ad8e68891cca3731, and as been backported to older kernels.\r
+\r
+If you see this error when using SELinux, ex: Android 4.4 or later\r
+ # ./gatord\r
+ Unable to load (insmod) gator.ko driver:\r
+ >>> gator.ko must be built against the current kernel version & configuration\r
+ >>> See dmesg for more details\r
+ # dmesg\r
+ ...\r
+ <7>[ 6745.475110] SELinux: initialized (dev gatorfs, type gatorfs), not configured for labeling\r
+ <5>[ 6745.477434] type=1400 audit(1393005053.336:10): avc: denied { mount } for pid=1996 comm="gatord-main" name="/" dev="gatorfs" ino=8733 scontext=u:r:shell:s0 tcontext=u:object_r:unlabeled:s0 tclass=filesystem\r
+disable SELinux so that gatorfs can be mounted by running\r
+ # setenforce 0\r
+Once gator is started, SELinux can be reenabled\r
\r
*** Profiling the kernel (optional) ***\r
\r
CONFIG_DEBUG_INFO must be enabled, see "Kernel configuration" section above.\r
Use vmlinux as the image for debug symbols in Streamline.\r
Drivers may be profiled using this method by statically linking the driver into the kernel image or adding the driver as an image to Streamline.\r
-To perform kernel stack unwinding and module unwinding, edit the Makefile to enable GATOR_KERNEL_STACK_UNWINDING and rebuild gator.ko.\r
+To perform kernel stack unwinding and module unwinding, edit the Makefile to enable GATOR_KERNEL_STACK_UNWINDING and rebuild gator.ko or run "echo 1 > /sys/module/gator/parameters/kernel_stack_unwinding" as root on the target after gatord is started.\r
\r
*** Automatically start gator on boot (optional) ***\r
\r
*** GPL License ***\r
\r
For license information, please see the file LICENSE after unzipping driver-src/gator-driver.tar.gz.\r
-\r