HotSpot 3.0 Documentation
-------------------------
CONTACT:
-------------------------
Main: http://lava.cs.virginia.edu/HotSpot
E-mail list subscription: http://www.cs.virginia.edu/mailman/listinfo/hotspot
Send e-mail: hotspot at cs dot virginia dot edu
-------------------------
This document assumes to a small extent that the reader is familiar 
with the previous versions of HotSpot. If anything is unclear, 
please read the README-1.0 and README-2.0 files for clarification.

CONTENTS
--------
	A) Installation
	B) What's new since version 2.0?
	C) Quick usage guide for the tools
		1) Base case - the block level thermal model
		2) The grid model
		3) The HotFloorplan floorplanner
	D) More detailed guidelines
		1) The block model
		2) The grid model
		3) HotFloorplan

INSTALLATION
------------
1. Download the HotSpot tar ball (HotSpot-3.0.tar.gz) following the
instructions at http://lava.cs.virginia.edu/HotSpot

2. Unzip and untar the file using the following commands
	a) gunzip HotSpot-3.0.tar.gz
	b) tar -xvf HotSpot-3.0.tar

3. Go to the HotSpot installation directory
	a) cd HotSpot-3.0/
	
4. Set the appropriate compiler flags and options in the Makefile

5. Build HotSpot
	a) make 

7. To remove all the outputs of compilation, type 'make clean'. To
remove the object files alone, type 'make cleano'. To view the list 
of files HotSpot needs for proper working, type 'make filelist'. 

WHAT'S NEW SINCE VERSION 2.0?
-----------------------------
1. A new grid-based thermal model that is better suited for transient
thermal simulation of a large numbers of blocks, blocks of radically
different sizes, and study of temperature gradients within blocks.

2. 3-D modeling. The grid model allows modeling for individual layers
within a die (device, metal, etc.) or stacked 3-D chips.

3. HotFloorplan, an architecture-level floorplanning tool for pre-RTL
design studies. It uses the classic simulated annealing algorithm and 
a thermal-aware objective function. 

4. Floorplan and thermal modeling of the dead space around the edge
of the die due to scribe lines.

5. Implementation of previously proposed, first-order wire-delay 
model for interconnects in the global and intermediate metal layers.

6. A thermal visualization tool for the grid model that outputs the
processor's thermal map as a color image in the SVG format.

7. Improved and hence significantly different interfaces including:
	a) Better command line support
	b) Better specification of parameters through a configuration file
	c) More modular code organization
	d) Switch to C++ compiler as parts of the grid model are in C++
	e) Improved documentation

QUICK USAGE GUIDE FOR THE TOOLS
-------------------------------
1. Base case - the block level thermal model:

Similar to version 2.0, the thermal model is bundled as a trace-level
simulator that takes a power trace file and a floorplan file as inputs 
and outputs the corresponding transient temperatures onto a 
temperature trace file. There is also an option to output the final 
steady state temperatures onto a file. With 'ev6.flp' as the given 
floorplan, 'gcc.ptrace' as the given power trace file (whose formats
are same as version 2.0), the set of commands to generate the 
temperature trace file 'gcc.ttrace' are given below. First let us
run the simulations with a set of default model parameters listed 
in the file 'hotspot.config' and gather the steady state 
temperatures onto a file. This is done by:
a) hotspot -c hotspot.config -f ev6.flp -p gcc.ptrace \
		   -o gcc.ttrace -steady_file gcc.steady

Now, 'gcc.ttrace' does contain a thermal trace but the initial 
temperatures that it used to generate it were default constant 
values, which might not be representative if the simulation is not 
long enough to warm up the chip and package. However, the steady 
state temperatures are a good estimate of what the correct set of 
initial temperatures are.  So, we now use the steady state 
temperatures produced as the set of initial temperatures for the 
next 'true' run:
b) cp gcc.steady gcc.init
   hotspot -c hotspot.config -init_file gcc.init -f ev6.flp \
   		   -p gcc.ptrace -o gcc.ttrace

2. The grid model:

The above runs were just the basic functionality provided since 
version 2.0. We will now try the added features of this release. The
thermal simulation above can be run using the grid model instead
of the block-level model. There are only two differences: 1) The
grid model can model 3-D chips and because of this capability,
it uses an additional input file 'layer.lcf'. This is the layer
configuration file that describes each layer of the stacked 3-D
chip and 2) The block model is the default setting for HotSpot
and hence we did not have to set any switch to choose it. For
the grid model, a model selection switch "-model_type grid" has
to be used for selection. Hence, the set of commands to  redo
the 2-pass thermal simulations above using the grid model is:
a) hotspot -c hotspot.config -f ev6.flp -p gcc.ptrace \
		   -o gcc.ttrace -steady_file gcc.steady \
		   -model_type grid -grid_layer_file layer.lcf
b) cp gcc.steady gcc.init
   hotspot -c hotspot.config -f ev6.flp -p gcc.ptrace \
		   -o gcc.ttrace -init_file gcc.init \
		   -model_type grid -grid_layer_file layer.lcf

Having mentioned the grid model's 3-D capability, we will
now show an example of its use. Let us use a simple, 3-block
floorplan file 'example.flp' in addition to 'ev6.flp'. In 
the chip we will model, layer 0 is silicon with a floorplan 
of 'example.flp', followed by a layer of thermal interface 
material. This is then followed by another layer of silicon 
with a floorplan of 'ev6.flp' and another layer of thermal 
interface material. Such a layer configuration is described
in 'example.lcf'. Also, we will just do a single-pass 
simulation with the default constant initial temperature 
values. So, we will ignore the '-steady_file' option. The 
command to do this is:
a) hotspot -c hotspot.config -f example.flp -p example.ptrace \
		   -o example.ttrace -model_type grid \
		   -grid_layer_file example.lcf

In addition to the '-steady_file' option that can be used with
the both the block and grid models, the grid model provides an
additional way to output the steady state temperatures. With
the '-steady_file' option, it outputs the temperatures in a 
format similar to the block model (i.e., single temperature 
corresponding to a single floorplan block). In this alternate
method, chosen by the command line switch '-grid_steady_file',
the internal grid temperatures are output directly (without
converting them into block temperatures). This can help in
learning how temperatures vary 'within' a block. Also, a 
perl script 'grid_thermal_map.pl' can produce an SVG format
color image of these temperatures with a superposed drawing 
of the floorplan 'example.flp' for viewing. If native viewer 
programs (e.g.: Adobe SVG viewer) are not available for viewing 
an SVG file, conversion tools like 'ImageMagick convert' can be 
used to generate alternate formats. Below is the set of commands 
to output grid temperatures onto a file called 'example.t' and 
to output the thermal map as a PDF image:
b) hotspot -c hotspot.config -f example.flp -p example.ptrace \
		   -o example.ttrace -model_type grid \
		   -grid_layer_file example.lcf \
		   -grid_steady_file example.t 
   grid_thermal_map.pl example.flp example.t > example.svg
   convert -font Helvetica svg:example.svg example.pdf

3. The HotFloorplan Floorplanner:

HotSpot comes with a thermal-aware floorplanning tool that
can be easily configured to optimize for an arbitrary objective 
function. It takes a listing of the functional block names,
areas, allowable aspect ratios and the connectivity between
the blocks as its input from a file. 'ev6.desc' is such a
'floorplan description' file (as opposed to the 'floorplan
file' ev6.flp). In order to evaluate the floorplans it 
generates for thermal merit, HotFloorplan also needs a set
of average power values for each of the functional blocks.
This is also specified in a file (e.g.: 'avg.p'). With these
files as inputs, the command to run HotFloorplan to produce
an output file 'output.flp' containing the floorplan 
generated is given by:
a) hotfloorplan -c hotspot.config -f ev6.desc -p avg.p \
				-o output.flp

If you run this command, please note that this typically
takes about 45 minutes to complete on a 2 GHz Athlon. It is
also to be noted that HotFloorplan uses only the block model
and not the grid model (the reasons are described below). The 
floorplan generated can be viewed (as in previous versions 
of HotSpot) using a FIG file viewer like 'XFig' and the perl 
script 'tofig.pl' which converts it into a FIG format. 
Alternatively, the command to convert this 'output.flp' into 
PDF using fig2dev and ps2pdf is:

b) tofig.pl output.flp  | fig2dev -L ps | ps2pdf - output.pdf


MORE DETAILED GUIDELINES
------------------------
While this section will try to provide more detailed explanation 
about the toolset's capabilities and guidelines for its use,
the maximum amount of information can be obtained only from the
source code itself. Looking at the 'Makefile' for this release,
one can see whether a source file corresponds to the block model,
the grid model, the floorplanner or the miscellaneous category.
Also, the input files that come with this release are well commented 
too. The formats of the floorplan, power trace, initial temperatures
etc. remain the same as the previous versions of HotSpot. For the
new files (e.g.: ev6.desc), the file format is explained in the 
comments found in them. Moreover, just running the tools without any
command line options gives a detailed listing of the available
options. Hence, we encourage the reader to try running the tools
and also to take a look at the respective source files, Makefile 
or the input files for more information about the tool that is not 
covered here. 

1. The block model:

a) The interfaces of hotspot have significantly changed. While this
   means that code that is already using previous versions of HotSpot
   has to be rewritten, we hope it would not be too difficult. The
   model is now more encapsulated and easier to integrate with an 
   existing tool. The two main interface functions 'compute_temp'
   and 'steady_state_temp' retain their names from the previous 
   releases of HotSpot but their parameters have changed slightly 
   according to the encapsulation of the thermal model. The function 
   'create_RC_matrices' has been split up into two functions -
   'populate_R_model' and 'populate_C_model'. This is done since
   'steady_state_temp' requires only the network of thermal 
   resistances for its computation. In applications where 
   'steady_state_temp' is called millions of times (e.g.: the 
   floorplanner), this reduction in computation of the thermal
   capacitances results in a huge performance improvement. The
   'sim-template_block.c' file provides a sample simulator use
   of the block model (just like 'sim-template.c' of the older
   HotSpot versions). A shorter code snippet that demonstrates the
   use of HotSpot in the user's code is shown below:

   #include "flp.h"
   #include "temperature.h"

   int main() 
   {

	char *flp_file, *power_file;
	char *init_temp_file, *steady_temp_file;

	flp_t *flp;
	RC_model_t *model;
	thermal_config_t config;
	double *power, *temp;
	double delta_t;

	flp = read_flp(flp_file, FALSE);
	config = default_thermal_config();
	model = alloc_RC_model(&config, flp);
	temp = hotspot_vector(model);
	power = hotspot_vector(model);

	read_power(model, power, power_file);
	read_temp(model, temp, init_temp_file, FALSE);

	populate_R_model(model, flp);
	populate_C_model(model, flp);

	compute_temp(model, power, temp, delta_t);
	steady_state_temp(model, power, temp);

	dump_temp(model, temp, steady_temp_file);

	delete_RC_model(model);
	free_flp(flp, FALSE);
	free_dvector(temp);
	free_dvector(power);

	return 0;
   }

b) Another difference in the basic HotSpot model between the current
   version and previous versions is the modeling of the dead space 
   around the edge of the die due to scribe lines. In the 'ev6.flp'
   floorplan, four blocks named 'RIM_*' have been added that surround
   the die. These dissipate zero power and are true dead spaces.

2. The grid model:

a) The grid model is faster than the block model for computing 
   the transient temperatures when there are a large number of
   functional blocks in a floorplan. It is to be noted however that
   it is much slower than the block model for computing the steady 
   state  temperatures. Hence, the grid model should be used only
   when there is a need for more accuracy (e.g.: when temperatures
   within a block are desired or when there is a large number of
   tiny blocks in the floorplan). More guidelines about the use
   of grid vs. block models can be found in the 'hotspot.c' file.
b) Of the inputs to the grid model, the floorplan file and the 
   layer configuration file have to be consistent with each other.
   The floorplan file should be the same as the floorplan specified 
   in layer 0 of the '.lcf' file. Also, it is to be noted that all 
   layers in the '.lcf' file must have the same width and height. 
   Further, the settings in the '.lcf' file (material properties, 
   thickness etc.) override the other global settings. Hence, care
   should be taken in ensuring that these settings are consistent
   with the values desired by the user. It is also to be noted
   that the non-power-dissipating layers of the '.lcf' file 
   (like the interface material layer) should have the same
   floorplan as the power-dissipating silicon layer above it.
   The 'layer.lcf' and 'example.lcf' files provided are a good
   example for the correct settings.
c) The modeling of a 3-D chip's thermal vias is not explicitly 
   supported in this release. But the users can get around it by
   manually changing the thermal conductivity for the grid cells 
   at which the thermal vias are supposed to be located to the 
   desired values.

3. HotFloorplan:

a) As mentioned above, one of the inputs to HotFloorplan is a 
   floorplan description file that has information about the 
   blocks to be floorplanned. In the file provided with this
   release ('ev6.desc'), the functional unit areas are same
   as 'ev6.flp'. The maximum aspect ratio constraint is set 
   to 1:3 except when a block has a bigger aspect ratio in the
   base floorplan 'ev6.flp'. In that case, the block's aspect
   ratio from 'ev6.flp' itself forms the upper limit. Also, 
   the connectivity section of 'ev6.desc' currently lists 13 
   major interconnects that we thought were important at the 
   architecture level. They are assumed to be of equal wire 
   density. Also, the wire_density field of the floorplan 
   description can be used to assign weights for the different
   wires according to their contribution to performance. In 
   'ev6.desc', the assignment of these weights is uniform 
   across all wires.
b) HotFloorplan includes a first-order wire-delay model for 
   wires in the global and intermediate metal layers. It is 
   a simple stand-alone model that converts wire length to 
   wire delay and can be used in any tool, whether the thermal 
   model, floorplan model, or any other simulator. It is 
   adapted from Otten and Brayton, DAC'98, and related work.
   The interfaces for the model are provided 'wire.[ch]'. An
   appropriate process technology node can be chosen by using 
   the TECHNODE #define in 'wire.h'. After that, the model is
   a simple call to the function 'wirelength2delay'.
c) HotFloorplan can be configured through many command line options.
   The 'hotspot.config' file clearly lists them and what they do.
   Among the options, following merit further discussion:
   i) Annealing parameters:
      The meaning of each these can be easily obtained from any
	  standard text on VLSI CAD that deals with simulated
	  annealing (e.g.: Sarrafzadeh and Wong, "An Introduction to
	  VLSI Physical Design", McGraw-Hill 1996). The original
	  DAC '86 paper by Wong and Liu on floorplanning is a very good 
	  starting point. 
  ii) Compaction ratio:
  	  During floorplanning, empty spaces can arise in a floorplan.
	  Sometimes, these spaces are just an artifact of the discrete
	  nature of the aspect ratio function of the individual
	  blocks. Typically, about 50% of the maximum possible number 
	  of dead spaces is due to this artifact. Such dead spaces 
	  are very tiny and hence can be safely ignored without any
	  impact on the thermal model. In fact, ignoring such blocks
	  reduces the size of the problem input to the thermal solver.
	  Since the thermal model's solver algorithm is a higher order
	  polynomial function in the number of functional blocks, 
	  ignoring the tiny blocks improves the performance of the
	  floorplanner significantly. The 'compact_ratio' option 
	  sets a threshold on the area of such tiny blocks. The
	  default is 0.5% of the area of the encompassing 'parent 
	  rectangle'. So, dead spaces that are smaller than 0.5% of
	  the parent rectangle are ignored during floorplanning. This
	  results in a maximum error in core area of about 0.46% for 
	  our experiments. This setting, combined with the 'n_orients'
	  setting that determines the magnitude of discreteness of
	  the blocks' aspect ratio function, can be tuned to manage
	  the trade-off between the speed and accuracy of the 
	  floorplanner. It is to be noted that in HotFloorplan, the 
	  empty spaces that are not compacted are named in the form 
	  _0, _1 and so on. It can be seen that the 'output.flp' 
	  generated from the steps discussed above has blocks named
	  in that form.
 iii) Weights for the metric (objective function):
	  HotFloorplan uses an objective function that is of the form 
	  lambdaA * A + lambdaT * T + lambdaW * W where A, T and W are 
	  the area, temperature and wire length respectively. The
	  weights lambdaA lambdaT and lambdaW can be set through
	  configuration parameters. Please note that for HotFloorplan,
	  A is in the order or hundreds of mm, T is in the order of 
	  hundreds of Kelvin and W is in the order of tens of mm. In
	  combining them to a single metric, the weights have to be
	  assigned in a manner that not only takes into account the
	  desired importance of the variables A, T and W but also 
	  compensates for the mismatch in their units of measurement.
	  The default weights in HotFloorplan are chosen based on this
	  principle. If one is interested in objective functions that 
	  are not in the above-mentioned form, it is quite easy to
	  make the change in HotFloorplan. The design of the simulated 
	  annealing algorithm is such that any arbitrary metric (objective 
	  function) can be incorporated. In HotFloorplan, this is done just 
	  by changing the return statement of the 'flp_evaluate_metric' 
	  function at the beginning of 'flp.c' into an appropriate objective
	  function of A, T and W.
d) For further information about HotFloorplan and the impact of floorplanning
   on temperature, please see the following paper: 
   K. Sankaranarayanan, S. Velusamy, M. R. Stan and K. Skadron, "A Case 
   for Thermal-Aware Floorplanning at the Microarchitectural Level." To
   appear in the Journal of Instruction-Level Parallelism, June 2005.
