README revision 10447
1DSENT (Design Space Exploration of Networks Tool)
2
3===============================================================================
4Overview
5===============================================================================
6DSENT is a modeling tool designed for rapid design space exploration of both
7electronical and emerging opto-electrical networks-on-chip (NoC). It provides
8analytic and parameterized models for various network components and is
9portable across a range of technology assumptions. Given architectural-level
10parameters, DSENT builds the specified models hierarchically from electrical
11and optical building blocks and outputs detailed power and area estimates. 
12
13
14===============================================================================
15Version
16===============================================================================
17Current: 0.91 (26 June 2012)
18
19Latest version or additional information can be found at
20
21    https://sites.google.com/site/mitdsent
22
23===============================================================================
24System requirements
25===============================================================================
26We have tested DSENT on the following platforms:
27
28Linux GNU g++ 4.1.2 and glibc 2.5
29Linux GNU g++ 4.3.2 and glibc 2.7
30Linux GNU g++ 4.4.5 and glibc 2.11.3
31Cygwin g++ 4.5.3 and cygwin 1.7.14
32
33===============================================================================
34License
35===============================================================================
36Please refer to the LICENSE file for licensing and copyright information.
37
38If you use DSENT in your research, please acknowledge us by referencing our 
39NOCS 2012 paper:
40
41Chen Sun, Chia-Hsin Owen Chen, George Kurian, Lan Wei, Jason Miller, 
42Anant Agarwal, Li-Shiuan Peh, Vladimir Stojanovic, "DSENT - A Tool Connecting 
43Emerging Photonics with Electronics for Opto-Electronic Networks-on-Chip 
44Modeling." The 6th ACM/IEEE International Symposium on Networks-on-Chip 
45(NOCS), May 2012, Lyngby, Denmark.
46
47
48===============================================================================
49Contact information
50===============================================================================
51If you have any questions or comments, please contact us through our mailing
52list at: mitdsent@mit.edu 
53
54We will try to reply as soon as possible.
55
56
57===============================================================================
58Build (installation)
59===============================================================================
60To build DSENT:
61
62    % make 
63
64By default DSENT is built with logging disabled. Logging keeps track of what 
65happens while running DSENT. It is an option more for the DSENT framework and 
66DSNET models developers. If you want to enable this option, simply type the 
67following: 
68
69    % make LIBUTIL_IS_LOG=true
70
71To clean the build: 
72
73    % make clean
74
75
76===============================================================================
77Usage
78===============================================================================
79DSENT builds models and runs based on the specified configuration file. In the 
80configuration file, you specify a model name and necessary information 
81(parameters and properties) required to build the model.
82
83To run DSENT:
84
85    % ./dsent -cfg <config_filename>
86
87To check what models are available:
88
89    % ./dsent -available_models
90
91To overwrite the configuration file from command line:
92    Use ';' to separate different key/value pairs. 
93
94    % ./dsent -cfg <config_filename> -overwrite <new query string>
95    % ./dsent -cfg configs/example.cfg -overwrite "NumberInputs=5; NumberOutputs=6;"
96
97To print out in a more human-friendly fasion:
98
99    % ./dsent -cfg <config_filename> -verbose
100
101To check what options are available:
102
103    % ./dsent -help
104
105Please see configs/example.cfg for an example of a configuration file.
106
107Please see configs/router.cfg for the router configuration file. 
108
109Please see QueryString and EvaluateString specifications below to know more 
110about the usage.
111
112===============================================================================
113Advanced Usage
114===============================================================================
115Since DSENT is a generic modeling framework for electrical and optical 
116components, you can create your own models. We will release guidelines on how 
117to create custom models on top of DSENT framework. You can use the provided 
118models as references.
119
120
121===============================================================================
122Quick start for Orion users
123===============================================================================
124Instead of using the SIM_port.h file, DSENT uses a text-based configuration 
125file to specify the router/link configurations. You do not need to recompile
126if you change parameters. Even though we use different parameter names, the
127ones we use should be self-explanatory. In this package, we provide template
128configuration files for the router and link:
129
130    router  - configs/router.cfg
131    link    - configs/electrical-link.cfg
132
133    Technology
134    ----------
135        We currently support 45, 32, 22, 11nm. You can specify the desired 
136        frequency but not the nominal voltage level since it is normally 
137        fixed in different processes. 
138
139    Router specs
140    ------------
141        Currently we only support the model of a widely used 3-pipeline-stage 
142        input-buffered virtual channel router and does not have distinction 
143        from ports for different components (cache, memory controller, I/O). 
144
145    Input buffer specs
146    ------------------
147        The number of virtual channels used for different message classes 
148        might be different; hence, DSENT uses NumberVirtualNetworks to 
149        specify the number of message classes and use 
150        NumberVirtualChannelsPerVirtualNetwork and 
151        NumberBuffersPerVirtualChannel to define the buffers needed for a  
152        virtual network (message class). 
153
154        Currently only DFF-based RAM is supports. This is reasonable since 
155        normally the buffer space needed at input port is small enough and 
156        does not need to use SRAMs or RFs (register files). 
157
158    Crossbar specs
159    --------------
160        Currently DSENT only supports multiplexer-based crossbars 
161        (MULTREE_CROSSBAR). You no longer need to specify the degree of the
162        multiplexers. 
163
164    Switch allocator specs
165    ----------------------
166        DSENT models a two-stage switch allocator. The first stage is used to 
167        arbitrate between VCs in the same input port, and the second stage is 
168        used to arbitrate between input ports. If there is only one VC in 
169        the input port, then the energy/power/area cost for the first stage 
170        will be zero. 
171        
172        Currently, DSENT supports MatrixArbiter. 
173
174    VC allocator specs
175    ------------------
176        We assume that the router uses a VC select scheme where the VC 
177        allocation is done by just popping a FIFO. Currently DSENT ignores 
178        this module since the FIFO that needs to keep the free VC information 
179        should be small enough. 
180
181    Clock distribution specs
182    ------------------------
183        Currently DSENT provides a broadcast H-Tree model. You can specify 
184        the number of levels of the H-Tree (normally 4 or 5 levels should be 
185        enough). 
186
187DSENT replaces the original orion_router_power, orion_router_area and 
188orion_link with QueryString and EvaluateString (see below for more detailed 
189information on how to use them). 
190
191
192===============================================================================
193QueryString specifications
194===============================================================================
195DSENT is a query-based model evaluator. You use QueryString to specify what 
196information you want DSENT to output. The syntax of a query string is shown as 
197follows: 
198
199    [Query type]>>[Instance name (with hierarchy)]:[Sub query type]@[Detail level]
200
201    E.g., Area>>Router->Crossbar:Active@4
202        * Query type:       Area
203        * Instance name:    Router->Crossbar
204        * Sub query type:   Active
205        * Detail level:     4
206
207    Query type
208    ----------
209        There are 9 types of queries: Parameter, Property, Energy, NddPower, 
210        Area, InstHier, EventHier, NddPowerHier, AreaHier. 
211
212        Parameter       - Print the model parameters needed to be specified 
213        Property        - Print the design constraints or utilization 
214            Use these to check what needs to be specified in the configuration 
215            file for the model. No sub query type is needed for these two 
216            types. 
217
218        Energy          - Print the data-dependent energy cost of an event
219        NddPower        - Print the non-data-denepent power of an instance
220        Area            - Print the area cost of an instance
221            Use these to obtain the costs of the specified model.
222
223        InstHier        - Print the instance name hierarchy
224            Use this to know what sub-instances are built for this model
225
226        EventHier       - Print the available events for Energy queries
227        NddPowerHier    - Print the available non-data-dependent power types
228        AreaHier        - Print the available area types
229            Use this to know what to specify in the "sub query type" field. 
230
231    Instance name (with hierarchy)
232    ------------------------------
233        The (sub)instance that you want to perform query. The name should be 
234        hierarchical starting from the top level model. Hierarchies are 
235        separated by the symbol "->".
236
237    Sub query type
238    --------------
239        This field is not required for 'Parameter', 'Property' and 'InstHier'.
240
241        For 'Energy', this field stands for the event that cause this energy 
242        cost, such as 'WriteBuffer'. 
243
244        For 'NddPower' and 'Area', this field stands for the power and area 
245        cost of the model, such as 'Leakage' and 'Active'. 
246
247        For 'EventHier', if this field is not specified, all events of this 
248        instance will be printed; if this field is specified, then only 
249        the specified event will be printed. 'AreaHier' and 'NddPowerHier' 
250        also have the similar behavior. 
251        
252    Detail level
253    ------------
254        Defines the hierarchy depth to be printed. '0' means current level. 
255        This field is needed for all query types for syntax correctness, 
256        although it is not used for 'Parameter' and 'Property'. 
257
258    Multi-line queries
259    ------------------
260        Query strings specified across multiple lines in the config file
261        must have each line be terminated by a '\'. It is whitespace sensitive,
262        so make sure there are no spaces after '\'. Note that the parser
263        prunes everything after the comment '#' character, including '\'!
264        See configs/router.cfg as an example.
265
266    Examples of individual QueryString's:
267
268        Parameter>>Router@0
269        Property>>Router->Crossbar@0
270        InstHier>>Router->InputPort@2
271        Energy>>Router:WriteBuffer@2
272        NddPower>>Router->Crossbar:Leakage@3
273        Area>>Router->SwitchAllocator:Active@4
274
275        
276===============================================================================
277EvaluateString specifications
278===============================================================================
279DSENT provides a way to let users do custom calculations by specifying the 
280EvaluateString in the configuration file. EvaluateString constains a sequence 
281of statements separated by one ';'. DSENT reads through the sequence and 
282evaluates the statements one-by-one. 
283
284Currently, DSENT supports:
285    Four arithmetic operations
286    --------------------------
287        3 + 4 * (5 + 6) / 7;
288
289    Define local variables through assignments
290    ------------------------------------------
291        variable 'a' will be mapped to 7 for future referencing
292
293        a = 3 + 4;
294
295    Global variable referencing
296    ---------------------------
297        $(var_name) indicates either a key in the configuration file or a 
298        query string. If var_name exists in the configuration file, then the 
299        corresponding value will be returned; otherwise, DSENT will do a query 
300        using the string var_name@0 and return the query result. 
301
302        b = $(Energy>>Router:WriteBuffer) * $(Frequency);
303
304    Printing outputs
305    ----------------
306        DSENT prints the string following the keyword 'print'. 
307
308        print <expression>
309        print "<string_to_print>";
310        print "<string_to_print>" <expression>;
311
312        print 3 + 4;                # Output: 7
313        print "Hello World";        # Output: Hello World
314        print "Hello World " 3 + 4; # Output: Hello World 7
315        
316    Multi-line evaluate strings
317    ---------------------------
318        Evaluate strings specified across multiple lines in the config file
319        must have each line be terminated by a '\'. It is whitespace sensitive,
320        so make sure there are no spaces after '\'. Note that the parser
321        prunes everything after the comment '#' character, including '\'!
322        See configs/router.cfg as an example.
323
324        
325===============================================================================
326Units
327===============================================================================
328DSENT uses only SI units for all inputs and outputs. For example:
329    time        = s (second)
330    distance    = m (meter)
331    capacitance = F (Farad)
332    power       = W (Watt)
333    energy      = J (Joule)
334    resistance  = Ohm
335    loss        = dB (Decibels)
336
337    
338===============================================================================
339Known Bugs and Issues
340===============================================================================
341
3421. If timing is not met, the timing optimizer will put the model in a state
343where everything is the maximum size (huge power, area). Thus, model results
344can be considered a gross over-estimate when timing isn't met. This is just the
345nature of the greedy timing optimizer and it will be addressed in the future.
346
3472. The VC control and credit buffer component of the router is currently
348not modeled, as they have always been assumed to be lumped into the "negligible
349control cost" category in previous models and evaluations. Our recent
350experiments have shown that this is not true and we will be adding this in the
351next iteration.
352
3533. Some of the connectivity paths have not been checked thoroughly. Thus,
354timing optimizer may miss some of the paths. However, we tried to make sure
355that the critical paths are modeled properly.
356
3574. Local interconnect will have an ever-larger impact on power and timing as
358technology scales. So far we have not implemented a method for automatically
359estimating them but we will eventually address this. Evaluations for 22nm
360and below will tend to underestimate as a result.
361
362===============================================================================
363Revision log
364===============================================================================
365V0.91:
366    Bugs fix:
367        1. Leakage power calculation printout for router (configs/router.cfg).
368
369    New feature:
370        1. Area printout for router (configs/router.cfg).
371
372V0.9:
373    First release.
374
375