gator: ARM DS-5.3 Streamline gator driver

Signed-off-by: Pawel Moll <pawel.moll@arm.com>

1 files changed, 117 insertions, 0 deletions

diff --git a/README_Streamline.txt b/README_Streamline.txt
new file mode 100644
index 0000000..4c52b7d
--- /dev/null
+++ b/README_Streamline.txt
@@ -0,0 +1,117 @@
+
+*** Purpose ***
+
+Instructions on setting up ARM Streamline on the target.
+The gator driver and gator daemon are required to run on the ARM linux target in order for ARM Streamline to operate.
+The driver should be built as a module and the daemon must run with root permissions on the target.
+
+*** Preparing and building the kernel ***
+
+cd into the root source dir of the linux kernel
+make ARCH=arm CROSS_COMPILE=${CROSS_TOOLS}/bin/arm-none-linux-gnueabi- <platform_defconfig> (choose the appropriate configuration for your board)
+make ARCH=arm CROSS_COMPILE=${CROSS_TOOLS}/bin/arm-none-linux-gnueabi- menuconfig
+
+Required Kernel Changes (depending on the kernel version, the location of these configuration settings within menuconfig may be different)
+- General Setup
+  - [*] Profiling Support
+- Kernel hacking
+  - [*] Tracers
+    - [*] Trace process context switches and events
+- Kernel Features
+  - [*] High Resolution Timer Support
+
+The "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.
+
+Optional Kernel Changes (depending on the kernel version, the location of these configuration settings within menuconfig may be different)
+Note: Configurations may not be supported on all targets
+- System Type
+  - [*] <SoC name> debugging peripherals (enable core performance counters on supported SoCs)  /* kernels before 2.6.35 */
+
+make -j5 ARCH=arm CROSS_COMPILE=${CROSS_TOOLS}/bin/arm-none-linux-gnueabi- uImage
+
+*** Building the gator module ***
+
+To create the gator.ko module,
+        cd /ds-5-install-directory/arm/src
+        tar xzf gator-driver.tar.gz
+        cd gator-driver
+        make -C <kernel_build_dir> M=`pwd` ARCH=arm CROSS_COMPILE=<...> modules
+for example
+        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
+If successful, a gator.ko module should be generated
+
+*** Compiling an application or shared library ***
+
+Recommended compiler settings:
+        "-g": Debug symbols needed for best analysis results.
+        "-fno-inline": Speed improvement when processing the image files and most accurate analysis results.
+        "-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).
+
+*** Running gator ***
+
+Load the kernel onto the target and copy gatord and gator.ko into the target's filesystem.
+gatord is located in <installdir>/arm/armv5t/.
+Ensure gatord has execute permissions
+        chmod +x gatord
+gator.ko must be located in the same directory as gatord on the target.
+With root privileges, run the daemon
+        sudo ./gatord &
+
+*** Profiling the kernel (optional) ***
+
+make ARCH=arm CROSS_COMPILE=$(CROSS_TOOLS}/bin/arm-none-linux-gnueabi- menuconfig
+- Kernel Hacking
+  - [*] Compile the kernel with debug info
+
+make -j5 ARCH=arm CROSS_COMPILE=${CROSS_TOOLS}/bin/arm-none-linux-gnueabi- uImage
+Use vmlinux as the image for debug symbols in Streamline.
+Drivers may be profiled using this method by statically linking the driver into the kernel image.
+Note that the gator driver does not perform kernel call stack recording.
+
+*** Automatically start gator on boot (optional) ***
+
+cd /etc/init.d
+vi rungator.sh
+        #!/bin/bash
+        /path/to/gatord &
+update-rc.d rungator.sh defaults
+
+*** Driver Sources ***
+
+Gator Sources
+        backtrace.c
+        cpu_buffer.c
+        cpu_fifo.c
+        cpu_fifo.h
+        gator_annotate.c
+        gator_events_irq.c
+        gator_init.c
+        gator_interrupt.c
+        gator_pmnc_armv7.c
+        gator_pmnc_none.c
+        gator_schedtrace.c
+        gator_setup.c
+        gator_timer.c
+        gator_traceprobe.h
+
+Oprofile Sources  // function names updated to avoid Oprofile collisions
+        buffer_sync.c
+        buffer_sync.h
+        cpu_buffer.h
+        event_buffer.c
+        event_buffer.h
+        oprof.h
+        oprofile.h
+        oprofile_files.c
+        oprofile_stats.c
+        oprofile_stats.h
+        timer_int.c
+
+Modified Oprofile Sources
+        buffer_sync.c   // modify sample contract to allow bad 'mm' or cookie
+        oprofilefs.c    // gatorfs and magic number
+        oprof.c         // updated module name and author
+
+*** GPL License ***
+
+For license information, please see the file LICENSE.