Power stress and shaping tool (PSST) - tool for controlled stress & monitor of x86 SoC for power/thermal analysis.

what can psst do:
=====================
psst is a controlled power virus for soc-sub components such as cpu, gpu & memory.
The intent is to expend power at different run-time-varying levels for analysis.
example of such analysis could be, a linear cpu hog function for governor evaluation,
a single step function for PID coefficient evaluaton etc,.

The fundamental difference with other power virus or monitor tools is that, the
work done during hog is not a dummy function, but own useful work functions such as
accounting, logging (in-memory), or power shape contour change etc. psst just executes
real work function duty-cycling in controlled loops. more work functions could be added to the
this tool overtime & they will be accounted for good -- against the ON-time of duty cycling.

The tool's most importat usecase is to do logging at a fixed "own" overhead -- not more than the present
requested load (active C0 percent). this ensures that monitoring does not influence the overall system
load (C0 %). This serves to monitor soc power/thermal parameters at much fine grained time, comparable
to governers's poll period (tens of ms).  For instance, a 100ms poll could causes upto 50% cpu overhead
in traditional tool. Fruthermore, psst's logging is aligned with the C0 activity that is
being analyzed.

USAGE
=====
usage:
psst [options <value>]
	Supported options are:
	-C|--cpumask		<CPUMASK> hex bit mask of cpu selected for stress. (default: every online cpu. Max 1024)
	-p|--poll-period	<pollperiod> (ms) for logging (default: 500 ms)
	-d|--duration		<duration> (ms) to run the tool (default: 3600000 i.e., 1hr)
	-l|--log-file		</path/to/log-file> (default: /var/log/pbot.csv)
	-v|--verbose		enables verbose mode (default: disabled)
	-V|--Version		prints version when specified
	-T|--track-max-cpu	Track the cpu# with maxed freq during poll period
	-h|--help		prints usage when specified
	-s|--shape-func		<shape-func,arg>
	Where supported power shape functions & args are:
		<single-step,v>		where v is load step height [C0%].(default shape: single-step,0.1)
		<sinosoid,w,a>		where w is wavelength [seconds] and a is the amplitude (max load %)
		<stair-case,v,u>	where v is load step height [C0%], u is step length (sec)
		<single-pulse,v,u>	where v is load step height [C0%], u is step length (sec)
		<linear-ramp,m>		where m is the slope (load/sec)
		<saw-tooth,m,a>		slope m (load/sec) reversed after max a% or min(0.1)%

example 1: use psst just for logging various power/thermal parameters
	   $./psst	 #same as $./psst -s single-step,0.1 -p 500 -v

example 2: linear ramp CPU power with slope 3% usage-per-secapplied for cpu1 & 3.
	  poll and reportevery 700mS. output on termial. run for 33 sec
	   $./psst -s linear-ramp,3 -C a -p 700 -d 33000 -v

more details on some options
============================
* -T|--track-max-cpu	Track the cpu# with maxed freq during poll period
  with this option, the cpu that requested max frequency in the poll window is determined & printed in output.
  one application of this, can be in determination of symmetric load distribution on SMP systems wherein each cpu
  gets equal % of hits.

Note: different cpu can be stressed with different funtions simultaneously. to do this just invoking separate
      commands for each cpu. Here is a fun example to demonstrate the controllability of linear ramp on cpu0,
      sine wave on cpu1, single-step on cpu2, single-pulse on cpu3 -- at the same time.

launch "system monitor" like utility & execute:
sleep 2; sudo ./psst -C 0 -d 30000 -s linear-ramp,2 &
sleep 2; sudo ./psst -C 1 -d 30000 -s sinosoid,15,50 &
sleep 2; sudo ./psst -C 2 -d 30000 -s single-step,20 &
sleep 5; sudo ./psst -C 3 -d 30000 -s single-pulse,60,2 &

Code structure
==============
.
|-- logger.c		# in-memory logging functions
|-- logger.h
|-- Makefile
|-- parse_config.c	# parse cmdline related routines
|-- parse_config.h
|-- perf_msr.c		# x86 msr counters for aperf/mperf etc
|-- perf_msr.h
|-- psst.c		# main routine & core work function
|-- psst.h
|-- rapl.c		# x86 energy register interface
|-- rapl.h
`-- README		# this file

Build
=====
 $sudo make
 $sudo ./psst
