# Copyright (c) 2016, Matthew Grosvenor, Noa Zilberman
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#
# * Redistributions of source code must retain the above copyright notice, this
#   list of conditions and the following disclaimer.
#
# * Redistributions in binary form must reproduce the above copyright notice,
#   this list of conditions and the following disclaimer in the documentation
#   and/or other materials provided with the distribution.
#
# * Neither the name of the project, the copyright holder nor the names of its
#  contributors may be used to endorse or promote products derived from
#   this software without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

This file documents the process required to run the kernel cold start latency test.
This test is close to a bare metal test, and starts just as the TSC counter starts.
Note that the process may change between platforms and OS.

Setup:
======
1. Download Linux kernel version 3.18.42 from www.kernel.org
2. cd /usr/src/3.18.42
3. make prepare
4. make menuconfig
          -> exit
  (this will save a default config file)
5. make -jX && make modules -jX && make modules_install
   in -jX, define a number that fits your number of core, e.g. for quad core
   make -j6 && make modules -j6 && make modules_install
6. Apply the patch file kernel_tsc_test.patch from within /usr/src/3.18.42/
   patch < kernel_tsc_test.patch
7. rm /boot/*3.18.42*
8. make & make install
9. Restart your machine, and at the boot menu select 3.18.42
   Note that the test takes a few minutes to run - it's not the machine hanging!
10. Once the OS is up, get the test results:
   dmesg | grep CUCL
11. Understanding the results:

[ ] CUCL START=<start cycle>, STOP=<end cycle>, DURATION=<total test duration in cycles>
[ ] CUCL  ******************************
[ ] CUCL  TSC TEST: Captured <N> samples > 64
[ ] CUCL  ******************************
[ ] CUCL  [<sample value> x 1],[<first time event happened>,<last time event happened>](0)
[ ] CUCL  ******************************
[ ] CUCL  Samples < thrshold (64) (and > 0):
[ ] CUCL  ******************************
[ ] CUCL  <sample value> cycles x <number of events of sample_value>
[ ] CUCL  *****************************


 
