diff options
authorPawel Moll2011-11-14 04:46:16 -0600
committerPawel Moll2011-11-17 12:04:47 -0600
commitbdf11fa03c80126715edd12da7196c52034da4f1 (patch)
tree2a56872f3466d6aec1f93944955ff058dbf5ea35 /README_Streamline.txt
parent8fc69a3638ca8d08111c161b1487868cb42cd888 (diff)
gator: Move README to top directory
... as it applies to both driver and daemon now. Signed-off-by: Pawel Moll <>
Diffstat (limited to 'README_Streamline.txt')
1 files changed, 108 insertions, 0 deletions
diff --git a/README_Streamline.txt b/README_Streamline.txt
new file mode 100644
index 0000000..0445e3f
--- /dev/null
+++ b/README_Streamline.txt
@@ -0,0 +1,108 @@
2*** Purpose ***
4Instructions on setting up ARM Streamline on the target.
5The gator driver and gator daemon are required to run on the ARM linux target in order for ARM Streamline to operate.
6The driver should be built as a module and the daemon must run with root permissions on the target.
8*** Introduction ***
10A linux development environment with cross compiling tools is most likely required, depending on what is already created and provided.
11-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.
12-The ideal development environment has the kernel source code available to be rebuilt and executed on the target. This environment allows the greatest flexibility in configuring the kernel and building the gator driver module.
13-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.
14 -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.
15 -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.
16 -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.
18*** Preparing and building the kernel ***
20cd into the root source dir of the linux kernel
21if your target has never been configured, choose the appropriate configuration for your target
22 make ARCH=arm CROSS_COMPILE=${CROSS_TOOLS}/bin/arm-none-linux-gnueabi- <platform_defconfig>
23make ARCH=arm CROSS_COMPILE=${CROSS_TOOLS}/bin/arm-none-linux-gnueabi- menuconfig
25Required Kernel Changes (depending on the kernel version, the location of these configuration settings within menuconfig may be different)
26- General Setup
27 - [*] Profiling Support
28- Kernel hacking
29 - [*] Tracers
30 - [*] Trace process context switches and events
31- Kernel Features
32 - [*] High Resolution Timer Support
33 - [*] Use local timer interrupts (only required for SMP)
35The "context switches and events" option will not be available if other trace configurations are enabled. Other trace configurations being enabled is sufficient to turn on context switches and events.
37Optional Kernel Changes (depending on the kernel version, the location of these configuration settings within menuconfig may be different)
38Note: Configurations may not be supported on all targets
39- System Type
40 - [*] <SoC name> debugging peripherals (enable core performance counters on supported SoCs) /* kernels before 2.6.35 */
42make -j5 ARCH=arm CROSS_COMPILE=${CROSS_TOOLS}/bin/arm-none-linux-gnueabi- uImage
44*** Checking the gator requirements ***
46(optional) Use the hrtimer_module utility to validate the kernel High Resolution Timer requirement.
48*** Building the gator module ***
50To create the gator.ko module,
51 cd /path/to/gator/driver-src
52 tar xzf gator-driver.tar.gz
53 cd gator-driver
54 make -C <kernel_build_dir> M=`pwd` ARCH=arm CROSS_COMPILE=<...> modules
55for example
56 make -C /home/username/kernel_2.6.32/ M=`pwd` ARCH=arm CROSS_COMPILE=/home/username/CodeSourcery/Sourcery_G++_Lite/bin/arm-none-linux-gnueabi- modules
57If successful, a gator.ko module should be generated
59*** Building the gator daemon ***
61cd /path/to/gator/daemon-src
62tar -xzf gator-daemon.tar.gz
63For Linux,
64 build with 'make'
65For Android,
66 mv gator-daemon jni
67 install the android ndk, see
68 /path/to/ndk/ndk-build
69 gatord should now be created and located in libs/armeabi
71*** Running gator ***
73Load the kernel onto the target and copy gatord and gator.ko into the target's filesystem.
74Ensure gatord has execute permissions
75 chmod +x gatord
76gator.ko must be located in the same directory as gatord on the target.
77With root privileges, run the daemon
78 sudo ./gatord &
80*** Compiling an application or shared library ***
82Recommended compiler settings:
83 "-g": Debug symbols needed for best analysis results.
84 "-fno-inline": Speed improvement when processing the image files and most accurate analysis results.
85 "-fno-omit-frame-pointer": ARM EABI frame pointers (Code Sourcery cross compiler) allow the call stack to be recorded with each sample taken when in ARM state (i.e. not -mthumb).
87*** Profiling the kernel (optional) ***
89make ARCH=arm CROSS_COMPILE=$(CROSS_TOOLS}/bin/arm-none-linux-gnueabi- menuconfig
90- Kernel Hacking
91 - [*] Compile the kernel with debug info
93make -j5 ARCH=arm CROSS_COMPILE=${CROSS_TOOLS}/bin/arm-none-linux-gnueabi- uImage
94Use vmlinux as the image for debug symbols in Streamline.
95Drivers may be profiled using this method by statically linking the driver into the kernel image or adding the module as an image.
96To perform kernel stack unwinding and module unwinding, edit the Makefile to enable GATOR_KERNEL_STACK_UNWINDING and rebuild gator.ko.
98*** Automatically start gator on boot (optional) ***
100cd /etc/init.d
102 #!/bin/bash
103 /path/to/gatord &
104update-rc.d defaults
106*** GPL License ***
108For license information, please see the file LICENSE after unzipping driver-src/gator-driver.tar.gz.