ext/dsent/README - public/gem5 - Git at Google

 DSENT (Design Space Exploration of Networks Tool)

 ===============================================================================
 Overview
 ===============================================================================
 DSENT is a modeling tool designed for rapid design space exploration of both
 electronical and emerging opto-electrical networks-on-chip (NoC). It provides
 analytic and parameterized models for various network components and is
 portable across a range of technology assumptions. Given architectural-level
 parameters, DSENT builds the specified models hierarchically from electrical
 and optical building blocks and outputs detailed power and area estimates.


 ===============================================================================
 Version
 ===============================================================================
 Current: 0.91 (26 June 2012)

 Latest version or additional information can be found at

     https://sites.google.com/site/mitdsent

 ===============================================================================
 System requirements
 ===============================================================================
 We have tested DSENT on the following platforms:

 Linux GNU g++ 4.1.2 and glibc 2.5
 Linux GNU g++ 4.3.2 and glibc 2.7
 Linux GNU g++ 4.4.5 and glibc 2.11.3
 Cygwin g++ 4.5.3 and cygwin 1.7.14

 ===============================================================================
 License
 ===============================================================================
 Please refer to the LICENSE file for licensing and copyright information.

 If you use DSENT in your research, please acknowledge us by referencing our
 NOCS 2012 paper:

 Chen Sun, Chia-Hsin Owen Chen, George Kurian, Lan Wei, Jason Miller,
 Anant Agarwal, Li-Shiuan Peh, Vladimir Stojanovic, "DSENT - A Tool Connecting
 Emerging Photonics with Electronics for Opto-Electronic Networks-on-Chip
 Modeling." The 6th ACM/IEEE International Symposium on Networks-on-Chip
 (NOCS), May 2012, Lyngby, Denmark.


 ===============================================================================
 Contact information
 ===============================================================================
 If you have any questions or comments, please contact us through our mailing
 list at: mitdsent@mit.edu

 We will try to reply as soon as possible.


 ===============================================================================
 Build (installation)
 ===============================================================================
 To build DSENT:

     % make

 By default DSENT is built with logging disabled. Logging keeps track of what
 happens while running DSENT. It is an option more for the DSENT framework and
 DSNET models developers. If you want to enable this option, simply type the
 following:

     % make LIBUTIL_IS_LOG=true

 To clean the build:

     % make clean


 ===============================================================================
 Usage
 ===============================================================================
 DSENT builds models and runs based on the specified configuration file. In the
 configuration file, you specify a model name and necessary information
 (parameters and properties) required to build the model.

 To run DSENT:

     % ./dsent -cfg <config_filename>

 To check what models are available:

     % ./dsent -available_models

 To overwrite the configuration file from command line:
     Use ';' to separate different key/value pairs.

     % ./dsent -cfg <config_filename> -overwrite <new query string>
     % ./dsent -cfg configs/example.cfg -overwrite "NumberInputs=5; NumberOutputs=6;"

 To print out in a more human-friendly fasion:

     % ./dsent -cfg <config_filename> -verbose

 To check what options are available:

     % ./dsent -help

 Please see configs/example.cfg for an example of a configuration file.

 Please see configs/router.cfg for the router configuration file.

 Please see QueryString and EvaluateString specifications below to know more
 about the usage.

 ===============================================================================
 Advanced Usage
 ===============================================================================
 Since DSENT is a generic modeling framework for electrical and optical
 components, you can create your own models. We will release guidelines on how
 to create custom models on top of DSENT framework. You can use the provided
 models as references.


 ===============================================================================
 Quick start for Orion users
 ===============================================================================
 Instead of using the SIM_port.h file, DSENT uses a text-based configuration
 file to specify the router/link configurations. You do not need to recompile
 if you change parameters. Even though we use different parameter names, the
 ones we use should be self-explanatory. In this package, we provide template
 configuration files for the router and link:

     router  - configs/router.cfg
     link    - configs/electrical-link.cfg

     Technology
     ----------
         We currently support 45, 32, 22, 11nm. You can specify the desired
         frequency but not the nominal voltage level since it is normally
         fixed in different processes.

     Router specs
     ------------
         Currently we only support the model of a widely used 3-pipeline-stage
         input-buffered virtual channel router and does not have distinction
         from ports for different components (cache, memory controller, I/O).

     Input buffer specs
     ------------------
         The number of virtual channels used for different message classes
         might be different; hence, DSENT uses NumberVirtualNetworks to
         specify the number of message classes and use
         NumberVirtualChannelsPerVirtualNetwork and
         NumberBuffersPerVirtualChannel to define the buffers needed for a
         virtual network (message class).

         Currently only DFF-based RAM is supports. This is reasonable since
         normally the buffer space needed at input port is small enough and
         does not need to use SRAMs or RFs (register files).

     Crossbar specs
     --------------
         Currently DSENT only supports multiplexer-based crossbars
         (MULTREE_CROSSBAR). You no longer need to specify the degree of the
         multiplexers.

     Switch allocator specs
     ----------------------
         DSENT models a two-stage switch allocator. The first stage is used to
         arbitrate between VCs in the same input port, and the second stage is
         used to arbitrate between input ports. If there is only one VC in
         the input port, then the energy/power/area cost for the first stage
         will be zero.

         Currently, DSENT supports MatrixArbiter.

     VC allocator specs
     ------------------
         We assume that the router uses a VC select scheme where the VC
         allocation is done by just popping a FIFO. Currently DSENT ignores
         this module since the FIFO that needs to keep the free VC information
         should be small enough.

     Clock distribution specs
     ------------------------
         Currently DSENT provides a broadcast H-Tree model. You can specify
         the number of levels of the H-Tree (normally 4 or 5 levels should be
         enough).

 DSENT replaces the original orion_router_power, orion_router_area and
 orion_link with QueryString and EvaluateString (see below for more detailed
 information on how to use them).


 ===============================================================================
 QueryString specifications
 ===============================================================================
 DSENT is a query-based model evaluator. You use QueryString to specify what
 information you want DSENT to output. The syntax of a query string is shown as
 follows:

     [Query type]>>[Instance name (with hierarchy)]:[Sub query type]@[Detail level]

     E.g., Area>>Router->Crossbar:Active@4
         * Query type:       Area
         * Instance name:    Router->Crossbar
         * Sub query type:   Active
         * Detail level:     4

     Query type
     ----------
         There are 9 types of queries: Parameter, Property, Energy, NddPower,
         Area, InstHier, EventHier, NddPowerHier, AreaHier.

         Parameter       - Print the model parameters needed to be specified
         Property        - Print the design constraints or utilization
             Use these to check what needs to be specified in the configuration
             file for the model. No sub query type is needed for these two
             types.

         Energy          - Print the data-dependent energy cost of an event
         NddPower        - Print the non-data-denepent power of an instance
         Area            - Print the area cost of an instance
             Use these to obtain the costs of the specified model.

         InstHier        - Print the instance name hierarchy
             Use this to know what sub-instances are built for this model

         EventHier       - Print the available events for Energy queries
         NddPowerHier    - Print the available non-data-dependent power types
         AreaHier        - Print the available area types
             Use this to know what to specify in the "sub query type" field.

     Instance name (with hierarchy)
     ------------------------------
         The (sub)instance that you want to perform query. The name should be
         hierarchical starting from the top level model. Hierarchies are
         separated by the symbol "->".

     Sub query type
     --------------
         This field is not required for 'Parameter', 'Property' and 'InstHier'.

         For 'Energy', this field stands for the event that cause this energy
         cost, such as 'WriteBuffer'.

         For 'NddPower' and 'Area', this field stands for the power and area
         cost of the model, such as 'Leakage' and 'Active'.

         For 'EventHier', if this field is not specified, all events of this
         instance will be printed; if this field is specified, then only
         the specified event will be printed. 'AreaHier' and 'NddPowerHier'
         also have the similar behavior.

     Detail level
     ------------
         Defines the hierarchy depth to be printed. '0' means current level.
         This field is needed for all query types for syntax correctness,
         although it is not used for 'Parameter' and 'Property'.

     Multi-line queries
     ------------------
         Query strings specified across multiple lines in the config file
         must have each line be terminated by a '\'. It is whitespace sensitive,
         so make sure there are no spaces after '\'. Note that the parser
         prunes everything after the comment '#' character, including '\'!
         See configs/router.cfg as an example.

     Examples of individual QueryString's:

         Parameter>>Router@0
         Property>>Router->Crossbar@0
         InstHier>>Router->InputPort@2
         Energy>>Router:WriteBuffer@2
         NddPower>>Router->Crossbar:Leakage@3
         Area>>Router->SwitchAllocator:Active@4


 ===============================================================================
 EvaluateString specifications
 ===============================================================================
 DSENT provides a way to let users do custom calculations by specifying the
 EvaluateString in the configuration file. EvaluateString constains a sequence
 of statements separated by one ';'. DSENT reads through the sequence and
 evaluates the statements one-by-one.

 Currently, DSENT supports:
     Four arithmetic operations
     --------------------------
         3 + 4 * (5 + 6) / 7;

     Define local variables through assignments
     ------------------------------------------
         variable 'a' will be mapped to 7 for future referencing

         a = 3 + 4;

     Global variable referencing
     ---------------------------
         $(var_name) indicates either a key in the configuration file or a
         query string. If var_name exists in the configuration file, then the
         corresponding value will be returned; otherwise, DSENT will do a query
         using the string var_name@0 and return the query result.

         b = $(Energy>>Router:WriteBuffer) * $(Frequency);

     Printing outputs
     ----------------
         DSENT prints the string following the keyword 'print'.

         print <expression>
         print "<string_to_print>";
         print "<string_to_print>" <expression>;

         print 3 + 4;                # Output: 7
         print "Hello World";        # Output: Hello World
         print "Hello World " 3 + 4; # Output: Hello World 7

     Multi-line evaluate strings
     ---------------------------
         Evaluate strings specified across multiple lines in the config file
         must have each line be terminated by a '\'. It is whitespace sensitive,
         so make sure there are no spaces after '\'. Note that the parser
         prunes everything after the comment '#' character, including '\'!
         See configs/router.cfg as an example.


 ===============================================================================
 Units
 ===============================================================================
 DSENT uses only SI units for all inputs and outputs. For example:
     time        = s (second)
     distance    = m (meter)
     capacitance = F (Farad)
     power       = W (Watt)
     energy      = J (Joule)
     resistance  = Ohm
     loss        = dB (Decibels)


 ===============================================================================
 Known Bugs and Issues
 ===============================================================================

 1. If timing is not met, the timing optimizer will put the model in a state
 where everything is the maximum size (huge power, area). Thus, model results
 can be considered a gross over-estimate when timing isn't met. This is just the
 nature of the greedy timing optimizer and it will be addressed in the future.

 2. The VC control and credit buffer component of the router is currently
 not modeled, as they have always been assumed to be lumped into the "negligible
 control cost" category in previous models and evaluations. Our recent
 experiments have shown that this is not true and we will be adding this in the
 next iteration.

 3. Some of the connectivity paths have not been checked thoroughly. Thus,
 timing optimizer may miss some of the paths. However, we tried to make sure
 that the critical paths are modeled properly.

 4. Local interconnect will have an ever-larger impact on power and timing as
 technology scales. So far we have not implemented a method for automatically
 estimating them but we will eventually address this. Evaluations for 22nm
 and below will tend to underestimate as a result.

 ===============================================================================
 Revision log
 ===============================================================================
 V0.91:
     Bugs fix:
         1. Leakage power calculation printout for router (configs/router.cfg).

     New feature:
         1. Area printout for router (configs/router.cfg).

 V0.9:
     First release.
	DSENT (Design Space Exploration of Networks Tool)

	===============================================================================
	Overview
	===============================================================================
	DSENT is a modeling tool designed for rapid design space exploration of both
	electronical and emerging opto-electrical networks-on-chip (NoC). It provides
	analytic and parameterized models for various network components and is
	portable across a range of technology assumptions. Given architectural-level
	parameters, DSENT builds the specified models hierarchically from electrical
	and optical building blocks and outputs detailed power and area estimates.


	===============================================================================
	Version
	===============================================================================
	Current: 0.91 (26 June 2012)

	Latest version or additional information can be found at

	https://sites.google.com/site/mitdsent

	===============================================================================
	System requirements
	===============================================================================
	We have tested DSENT on the following platforms:

	Linux GNU g++ 4.1.2 and glibc 2.5
	Linux GNU g++ 4.3.2 and glibc 2.7
	Linux GNU g++ 4.4.5 and glibc 2.11.3
	Cygwin g++ 4.5.3 and cygwin 1.7.14

	===============================================================================
	License
	===============================================================================
	Please refer to the LICENSE file for licensing and copyright information.

	If you use DSENT in your research, please acknowledge us by referencing our
	NOCS 2012 paper:

	Chen Sun, Chia-Hsin Owen Chen, George Kurian, Lan Wei, Jason Miller,
	Anant Agarwal, Li-Shiuan Peh, Vladimir Stojanovic, "DSENT - A Tool Connecting
	Emerging Photonics with Electronics for Opto-Electronic Networks-on-Chip
	Modeling." The 6th ACM/IEEE International Symposium on Networks-on-Chip
	(NOCS), May 2012, Lyngby, Denmark.


	===============================================================================
	Contact information
	===============================================================================
	If you have any questions or comments, please contact us through our mailing
	list at: mitdsent@mit.edu

	We will try to reply as soon as possible.


	===============================================================================
	Build (installation)
	===============================================================================
	To build DSENT:

	% make

	By default DSENT is built with logging disabled. Logging keeps track of what
	happens while running DSENT. It is an option more for the DSENT framework and
	DSNET models developers. If you want to enable this option, simply type the
	following:

	% make LIBUTIL_IS_LOG=true

	To clean the build:

	% make clean


	===============================================================================
	Usage
	===============================================================================
	DSENT builds models and runs based on the specified configuration file. In the
	configuration file, you specify a model name and necessary information
	(parameters and properties) required to build the model.

	To run DSENT:

	% ./dsent -cfg <config_filename>

	To check what models are available:

	% ./dsent -available_models

	To overwrite the configuration file from command line:
	Use ';' to separate different key/value pairs.

	% ./dsent -cfg <config_filename> -overwrite <new query string>
	% ./dsent -cfg configs/example.cfg -overwrite "NumberInputs=5; NumberOutputs=6;"

	To print out in a more human-friendly fasion:

	% ./dsent -cfg <config_filename> -verbose

	To check what options are available:

	% ./dsent -help

	Please see configs/example.cfg for an example of a configuration file.

	Please see configs/router.cfg for the router configuration file.

	Please see QueryString and EvaluateString specifications below to know more
	about the usage.

	===============================================================================
	Advanced Usage
	===============================================================================
	Since DSENT is a generic modeling framework for electrical and optical
	components, you can create your own models. We will release guidelines on how
	to create custom models on top of DSENT framework. You can use the provided
	models as references.


	===============================================================================
	Quick start for Orion users
	===============================================================================
	Instead of using the SIM_port.h file, DSENT uses a text-based configuration
	file to specify the router/link configurations. You do not need to recompile
	if you change parameters. Even though we use different parameter names, the
	ones we use should be self-explanatory. In this package, we provide template
	configuration files for the router and link:

	router - configs/router.cfg
	link - configs/electrical-link.cfg

	Technology
	----------
	We currently support 45, 32, 22, 11nm. You can specify the desired
	frequency but not the nominal voltage level since it is normally
	fixed in different processes.

	Router specs
	------------
	Currently we only support the model of a widely used 3-pipeline-stage
	input-buffered virtual channel router and does not have distinction
	from ports for different components (cache, memory controller, I/O).

	Input buffer specs
	------------------
	The number of virtual channels used for different message classes
	might be different; hence, DSENT uses NumberVirtualNetworks to
	specify the number of message classes and use
	NumberVirtualChannelsPerVirtualNetwork and
	NumberBuffersPerVirtualChannel to define the buffers needed for a
	virtual network (message class).

	Currently only DFF-based RAM is supports. This is reasonable since
	normally the buffer space needed at input port is small enough and
	does not need to use SRAMs or RFs (register files).

	Crossbar specs
	--------------
	Currently DSENT only supports multiplexer-based crossbars
	(MULTREE_CROSSBAR). You no longer need to specify the degree of the
	multiplexers.

	Switch allocator specs
	----------------------
	DSENT models a two-stage switch allocator. The first stage is used to
	arbitrate between VCs in the same input port, and the second stage is
	used to arbitrate between input ports. If there is only one VC in
	the input port, then the energy/power/area cost for the first stage
	will be zero.

	Currently, DSENT supports MatrixArbiter.

	VC allocator specs
	------------------
	We assume that the router uses a VC select scheme where the VC
	allocation is done by just popping a FIFO. Currently DSENT ignores
	this module since the FIFO that needs to keep the free VC information
	should be small enough.

	Clock distribution specs
	------------------------
	Currently DSENT provides a broadcast H-Tree model. You can specify
	the number of levels of the H-Tree (normally 4 or 5 levels should be
	enough).

	DSENT replaces the original orion_router_power, orion_router_area and
	orion_link with QueryString and EvaluateString (see below for more detailed
	information on how to use them).


	===============================================================================
	QueryString specifications
	===============================================================================
	DSENT is a query-based model evaluator. You use QueryString to specify what
	information you want DSENT to output. The syntax of a query string is shown as
	follows:

	[Query type]>>[Instance name (with hierarchy)]:[Sub query type]@[Detail level]

	E.g., Area>>Router->Crossbar:Active@4
	* Query type: Area
	* Instance name: Router->Crossbar
	* Sub query type: Active
	* Detail level: 4

	Query type
	----------
	There are 9 types of queries: Parameter, Property, Energy, NddPower,
	Area, InstHier, EventHier, NddPowerHier, AreaHier.

	Parameter - Print the model parameters needed to be specified
	Property - Print the design constraints or utilization
	Use these to check what needs to be specified in the configuration
	file for the model. No sub query type is needed for these two
	types.

	Energy - Print the data-dependent energy cost of an event
	NddPower - Print the non-data-denepent power of an instance
	Area - Print the area cost of an instance
	Use these to obtain the costs of the specified model.

	InstHier - Print the instance name hierarchy
	Use this to know what sub-instances are built for this model

	EventHier - Print the available events for Energy queries
	NddPowerHier - Print the available non-data-dependent power types
	AreaHier - Print the available area types
	Use this to know what to specify in the "sub query type" field.

	Instance name (with hierarchy)
	------------------------------
	The (sub)instance that you want to perform query. The name should be
	hierarchical starting from the top level model. Hierarchies are
	separated by the symbol "->".

	Sub query type
	--------------
	This field is not required for 'Parameter', 'Property' and 'InstHier'.

	For 'Energy', this field stands for the event that cause this energy
	cost, such as 'WriteBuffer'.

	For 'NddPower' and 'Area', this field stands for the power and area
	cost of the model, such as 'Leakage' and 'Active'.

	For 'EventHier', if this field is not specified, all events of this
	instance will be printed; if this field is specified, then only
	the specified event will be printed. 'AreaHier' and 'NddPowerHier'
	also have the similar behavior.

	Detail level
	------------
	Defines the hierarchy depth to be printed. '0' means current level.
	This field is needed for all query types for syntax correctness,
	although it is not used for 'Parameter' and 'Property'.

	Multi-line queries
	------------------
	Query strings specified across multiple lines in the config file
	must have each line be terminated by a '\'. It is whitespace sensitive,
	so make sure there are no spaces after '\'. Note that the parser
	prunes everything after the comment '#' character, including '\'!
	See configs/router.cfg as an example.

	Examples of individual QueryString's:

	Parameter>>Router@0
	Property>>Router->Crossbar@0
	InstHier>>Router->InputPort@2
	Energy>>Router:WriteBuffer@2
	NddPower>>Router->Crossbar:Leakage@3
	Area>>Router->SwitchAllocator:Active@4


	===============================================================================
	EvaluateString specifications
	===============================================================================
	DSENT provides a way to let users do custom calculations by specifying the
	EvaluateString in the configuration file. EvaluateString constains a sequence
	of statements separated by one ';'. DSENT reads through the sequence and
	evaluates the statements one-by-one.

	Currently, DSENT supports:
	Four arithmetic operations
	--------------------------
	3 + 4 * (5 + 6) / 7;

	Define local variables through assignments
	------------------------------------------
	variable 'a' will be mapped to 7 for future referencing

	a = 3 + 4;

	Global variable referencing
	---------------------------
	$(var_name) indicates either a key in the configuration file or a
	query string. If var_name exists in the configuration file, then the
	corresponding value will be returned; otherwise, DSENT will do a query
	using the string var_name@0 and return the query result.

	b = $(Energy>>Router:WriteBuffer) * $(Frequency);

	Printing outputs
	----------------
	DSENT prints the string following the keyword 'print'.

	print <expression>
	print "<string_to_print>";
	print "<string_to_print>" <expression>;

	print 3 + 4; # Output: 7
	print "Hello World"; # Output: Hello World
	print "Hello World " 3 + 4; # Output: Hello World 7

	Multi-line evaluate strings
	---------------------------
	Evaluate strings specified across multiple lines in the config file
	must have each line be terminated by a '\'. It is whitespace sensitive,
	so make sure there are no spaces after '\'. Note that the parser
	prunes everything after the comment '#' character, including '\'!
	See configs/router.cfg as an example.


	===============================================================================
	Units
	===============================================================================
	DSENT uses only SI units for all inputs and outputs. For example:
	time = s (second)
	distance = m (meter)
	capacitance = F (Farad)
	power = W (Watt)
	energy = J (Joule)
	resistance = Ohm
	loss = dB (Decibels)


	===============================================================================
	Known Bugs and Issues
	===============================================================================

	1. If timing is not met, the timing optimizer will put the model in a state
	where everything is the maximum size (huge power, area). Thus, model results
	can be considered a gross over-estimate when timing isn't met. This is just the
	nature of the greedy timing optimizer and it will be addressed in the future.

	2. The VC control and credit buffer component of the router is currently
	not modeled, as they have always been assumed to be lumped into the "negligible
	control cost" category in previous models and evaluations. Our recent
	experiments have shown that this is not true and we will be adding this in the
	next iteration.

	3. Some of the connectivity paths have not been checked thoroughly. Thus,
	timing optimizer may miss some of the paths. However, we tried to make sure
	that the critical paths are modeled properly.

	4. Local interconnect will have an ever-larger impact on power and timing as
	technology scales. So far we have not implemented a method for automatically
	estimating them but we will eventually address this. Evaluations for 22nm
	and below will tend to underestimate as a result.

	===============================================================================
	Revision log
	===============================================================================
	V0.91:
	Bugs fix:
	1. Leakage power calculation printout for router (configs/router.cfg).

	New feature:
	1. Area printout for router (configs/router.cfg).

	V0.9:
	First release.