rustamc / wotan Goto Github PK

README
by Oleg Petelin ([email protected])
Modified September 2016


**** OUTLINE ****
A description of the Wotan algorithm can be found in Chapter 5 of Oleg's MASc thesis. This README document explains how to run Wotan and use the associated scripts. A description of the important files and folders is below:

     ./wotan     -- the main Wotan executable created by running 'make'
     ./SRC/      -- Wotan source code
     ./python/   -- python scripts used to automate Wotan/VPR runs
     ./arch/     -- holds templates for VPR architecture files based on 6-LUT and 4-LUT logic blocks.
                    used by ./python/arch_handler.py to automatically create architectures
                    with different parameters (switch blocks, Fc values, segment depopulation).
      

**** BASIC WOTAN COMMANDS ****
Wotan uses a routing resource graph generated by VPR. You can get VPR, and find the corresponding documentation, at:

	https://github.com/verilog-to-routing/vtr-verilog-to-routing

"router_lookahead" is the most reliable VPR branch for working with Wotan (for now), so switch to that. To generate (create a file of) the routing resource graph using VPR, run:

	./vpr <architecture_file> <benchmark_file> -dump_rr_structs_file <dumped_rr_structs_file>
             -route_chan_width <chan_width> -nodisp

The -dump_rr_structs_file option will cause VPR to print the routing resource data structures, after which VPR will automatically close. With this command VPR will dump the routing structures as they are right before the placement stage, so the routing graph will consist of only logic blocks and I/O pads (even if the architecture specifies other hard blocks like DSPs and memories). Also note that the <architecture_file> and <benchmark_file> inputs to VPR will determine aspects of the routing resource graph, such as the switch patterns in the routing fabric and the size of the FPGA that Wotan will work with.

'path_dependence' is the best branch to currently run Wotan. To run Wotan using the dumped routing resource structs file and some 'good' command line options, run:

	./wotan -rr_structs_file <dumped_rr_structs_file> -threads <threads> 
		-demand_multiplier <demand_mult> -max_connection_length 8

Where:
      -threads            -- will run Wotan with the specified number of CPU threads (can significantly
                             decrease runtime)

      -demand_multiplier  -- referred to as "alpha" in Chapter 5 of the MASc thesis, this is a multiplier
                             applied to the congestion probabilities (demands) placed on nodes. An
                             appropriate value depends on the routing architecture being evaluated,
                             and the scripts in the ./python/ folder will find this value automatically
                             (they perform a binary search, changing the demand multiplier until
                             the architecture reliability is approximately 0.5. the demand multiplier
                             is then interpreted as the final routability metric)

      -max_connection_length    -- path enumeration is performed between sources and sinks that are
                                   at most this Manhattan distance apart. Values between 4 and 8
                                   are reasonable tradeoffs of runtime and result quality


Running Wotan with these command line options will make Wotan perform the congestion estimation and routing probability evaluation steps, printing the network reliability of the routing architecture at the specified value of the demand multiplier (along with other internal metrics along the way).


**** WOTAN GRAPHICS ****
To display Wotan graphics, set 'ENABLE_GRAPHICS = true' in the Wotan Makefile. Your machine should be capable of X11 graphics for this to work. The Wotan command-line option '-nodisp' can always be used to supress graphics after compiling Wotan with grahpics enabled.


**** PYTHON SCRIPTS ****
The python scripts are used to calculate Wotan's absolute routability metric (as opposed to the (intermediate) network reliability value obtained by running Wotan once), and to automate Wotan runs over large lists of architectures. Unfortunately, the scripts became increasingly messy and full of spaghetti code as Wotan evolved, and they are in dire need of cleanup. Their basic use is described below.

	tester_script.py  -- the top-level python script to run Wotan tests. The key parameters to look
                             for are:
              - anything under ### Paths ### -- make sure the paths match your file system
              - wotan_opts -- basic wotan command-line options
              - arch_list -- the list of architectures that wotan will evaluate
	wotan_tester.py  -- classes and functions to run Wotan/VPR tests. Lots of stuff here, but the
                            main function for the basic Wotan flow is 'evaluate_architecture_list'.
                            This function is unfortunately hard coded. There you can set
                            the channel widths that you want to run the tests over, as well as VPR
                            seeds (if doing VPR routability evaluation). This function also sets the benchmark circuit
                            that is used for dumping the VPR routing resource graph.

                            Another important function is 'my_custom_archs_list', which holds a list of
                            strings representing architecture points to be evaluated.

So what does a flow with these (admittedly messy) scripts look like?
1) Specify your routing architectures in wotan_tester.py :: my_custom_archs_list
2) Choose your channel widths (and VPR seeds, if evaluating routability with VPR) 
   in wotan_tester.py :: evalaute_architecture_list
3) Modify paths and/or Wotan command line options in tester_script.py
4) Run tester_script.py

If runnning on a machine through ssh, it is useful to run as:

	nohup python tester_script.py > script_output.out &

which will keep your tests running even if your ssh connection terminates.

At the end of this flow you will have a list of absolute Wotan routability metrics for each of the architectures (along with VPR minW values, if VPR was used to evaluate routability), and some other peripheral outputs.