Instructions & guidelines to use Streamline with Cluster Switching
==================================================================

A   Introduction

    This note describes how the Virtualizer software and the Streamline
    tools should be configured to be able to visualize cluster Switching
    and PMU counters across switches.

B   Guidelines

    Setting up your target

    1.  Setup Gator

        These instructions are specific to the following big.LITTLE Migration
        target: ARM Linux on Real-Time System Model v7.0.1 with the
        Virtualizer.

        You have to build the Virtualizer specific gator daemon and the gator
        driver.

        Follow the instruction in paragraph 'Setting up an ARM Linux target'
        which you can find in ARM DS-5 Documentation in ARM Streamline >
        Setting Up Your Target (click Help->Help Contents in your DS-5 Eclipse
        window).

        Note that the documentation you find there does not cover the
        big.LITTLE Migration target. You have to consider the following
        variations:

        *  Source code for the Gator driver (gator-driver.tar.gz) and daemon
           (gator-daemon.tar.gz) are in the extra/gator subdirectory of the
           Virtualizer release tarball.

        *  To build the Gator driver, use the Linux kernel source as well as
           the configuration file mentioned in docs/03-Linux-kernel-build.txt.
           The configuration file has all the necessary Kernel configuration
           options for gator enabled already.

        *  The Streamline version in DS-5 V5.9 supports the Real-Time System
           Model v7.0.1. For this specific model, you get values for the PMU
           Cycle counter, the Instruction TLB refill counter and the
           Instructions executed counter. Since an RTSM does not provide
           accurate cycle and timing information the samples-generated data is
           still not meaningful. However, it is sufficient to showcase and
           validate the mechanisms required to use the PMUs with the
           Virtualizer.

        *  A default counter configuration file 'configuration.xml' is provided
           in the extra/gator subdirectory of the Virtualizer release tarball.
           Note, that you can always configure counters using DS-5's counters
           configuration dialog box but the existing configuration.xml already
           enables all meaningful counters on the Real-Time System Model v7.0.1.

        *  Copy gatord, gator.ko and configuration.xml into the same directory
           of the target file system.

        *  Run gatord with the default port 8080 since a corresponding setup is
           done in the mxscripts for the gatord listening port in user-mode
           networking:
           $ ./gatord &

    2.  Setup user-mode networking

        *  Invoke the model with the network (string networking) related
           options depicted in the big-little-mp<x>.mxscript file (x is 1 or 4
           as the case may be).

        *  Configure an IP address on the network interface of the target.
           There are multiple ways to do it, one would be the following:

           Activate the network interface:
           $ ifconfig eth0 up

           Invoke DHCP client on the network interface (e.g. udhcpc in
           Busybox) to obtain an ip address:

           $ IP_ADDR=`udhcpc -i eth0 2>/dev/null | grep "^Lease" |
             awk '{print $3}'`

           Add the ip address to the network interface:

           $ ifconfig eth0 $IP_ADDR

    Running a Streamline session

    1.  You can now connect from your DS-5 ARM Streamline Data view to the
        target by providing 'localhost' into the Address field and press the
        'Start capture' button.

    2.  Invoke cluster switches. Please follow the instruction in
        Documentation/cpu-freq/cpufreq-arm-bl.txt in the Linux kernel source
        mentioned in docs/03-Linux-kernel-build.txt.

    3.  Press the 'Stop' button of the current Capture and evaluate the
        graphical representation of the PMU counters mentioned above as well
        as the switching counts.