###############################################################
# New Developer Tutorial
#
# By Jason Luu
# May 8, 2013
###############################################################

Welcome to the Verilog-to-Routing (VTR) Project.  This project is an 
open-source, international, collaboration towards a comprehensive FPGA 
architecture exploration system that includes CAD tools, benchmarks, 
transistor-optimized architecture files, and documentation, along with support 
to make this all fit together and work.  The purpose of this tutorial is to 
equip you, the new developer, with the tools and understanding that you need to 
begin making a useful contribution to this project.

While you are going through this tutorial, please record down things that should 
be changed.  Whether it is the tutorial itself, documentation, or other parts of 
the VTR project.  Your thoughts are valuable and welcome because fresh eyes help 
evaluate whether or not our work is clearly presented.

Task #1 - Environment Setup

  1.  Log into your workstation/personal computer.  Check your account for 
  general features such as internet, printing, git, etc.  If there are problems 
  at this stage, talk to your advisor to get this setup.

  2.  If you are not familiar with development on Linux, this is the time to get 
  up to speed.  Look up online tutorials on general commands, basic development 
  using Makefiles, etc.

Task #2 - Background Reading

  1.  Read the first two chapters of "Architecture and CAD for deep-submicron 
  FPGAs" by Vaughn Betz, et al.  This is a great introduction to the topic of 
  FPGA CAD and architecture.  Note though that this book is old so it only 
  covers a small core of what the VTR project is currently capable of.  

  2.  Read chapters 1 to 5 of "FPGA Architecture: Survey and Challenges" by Ian 
  Kuon et al.

  3.  Review material learned with fellow colleagues.

Task #3 - Setup VTR

  1.  Use git to clone a copy of VTR from 
 https://github.com/verilog-to-routing/vtr-verilog-to-routing

  2.  Build the project

  3.  Run "./run_quick_test.py" to check that the build worked

  4.  Follow the Basic Design Flow Tutorial found in the Tutorials
  section of the documentation (https://vtr.readthedocs.io/en/latest).
  This tutorial will allow you to run a circuit through the entire flow
  and read the statistics gathered from that run.

Task #4 - Use VTR

  1.  Create your own custom Verilog file.  Create your own custom architecture 
  file using one of the existing architecture files as a template.  Use VTR to 
  map that circuit that you created to that architecture that you created. The VTR
  documentation, to be found at https://vtr.readthedocs.io/en/latest/
  will prove useful. You may also wish to look at the following links for descriptions
  of the language used inside the architecture files:
  - http://www.eecg.utoronto.ca/~jluu/publications/luu_vpr_fpga2011.pdf
  - http://www.eecg.utoronto.ca/vpr/utfal_ex1.html

  2.  Perform a simple architecture experiment.  Run an experiment that varies 
  Fc_in from 0.01 to 1.00 on the benchmarks ch_intrinsics, or1200, and sha.  Use 
  tasks/timing as your template.  Graph the geometric average of minimum channel 
  width and critical path delay for these three benchmarks across your different 
  values of Fc_in.  Review the results with your colleagues and/or advisor.

Task #5 - Open the Black Box

  At this stage, you have gotten a taste of how an FPGA architect would go about 
  using VTR.  As a developer though, you need a much deeper understanding of how 
  this tool works.  The purpose of this section is to have you to learn the 
  details of the VTR CAD flow by having you manually do what the scripts do.

  1.  Using the custom Verilog circuit and architecture created in Task #4, 
  directly run Odin II on it to generate a blif netlist.  You may need to skim the Odin II
  readme file and the vtr_flow/scripts/run_vtr_flow.py.

  2.  Using the output netlist of Odin II, run ABC to generate a technology-mapped blif file.
  You may need to skim vtr_flow/scripts/run_vtr_flow.py.

  3.  Using the output of ABC, run VPR to complete the mapping of a user circuit 
  to a target architecture.  You may need to consult the VPR User Manual and skim
  You may need to skim vtr_flow/scripts/run_vtr_flow.py.

  4.  Read the VPR section of the online documentation.

Task #6 - Submitting Changes and Regression Testing

  1.  Read README.developers.md in the base directory of VTR. Code changes rapidly
  so please help keep this up to date if you see something that is out of date.

  2.  Make your first change to git by modifying README.txt and pushing it.  I recommend 
  adding your name to the list of contributors.  If you have
  nothing to modify, just add/remove a line of whitespace at the bottom of the file.


Now that you have completed the tutorial, you should have a general sense of what 
the VTR project is about and how the different parts work together.  It's time
to talk to your advisor to get your first assignment.


Good luck!