==========================================================

Repository containing the Beam Position Monitor FPGA firmware and 
software.

==========================================================

Folder Hierarchy organization:

*
|
|-- hdl:
|    |   HDL (Verilog/VHDL) cores related to the BPM.
|    |  
|    |-- ip_cores:
|    |    |   Third party reusable modules, primarily Open hardware 
|    |    |     modules (http://www.ohwr.org).
|    |    |
|    |    |-- etherbone-core:
|    |    |       Connects two Wishbone Busses, either a true hardware bus
|    |    |         or emulated software bus, throught Ethernet.
|    |    |-- general-cores (fork from original projecct): 
|    |            General reusable modules.
|    |
|    |-- modules:
|    |    |   Modules specific to BPM hardware.
|    |    |  
|    |    |-- custom_common:
|    |    |       Common (reusable) modules to BPM hardware and possibly 
|    |    |         to other designs.
|    |    |-- custom_wishbone:
|    |            Wishbone modules to BPM hardware.
|    |
|    |-- platform:
|    |        Platform-specific code, such as xilinx chipscope wrappers.
|    |
|    |-- sim:
|    |        Generic simulation files, reusable Bus Functional Modules (BFM),
|    |          constants definitions.
|    |
|    |-- syn:
|    |       Synthesis specific files (user constraints files and top design 
|    |          specification).
|    |
|    |-- testbench:
|    |       Testbenches for modules and top level designs. May use modules
|    |         defined elsewhere (specific within the 'sim" directory).
|    |
|    |-- top:
|            Top design modules.     
|      
|-- sw:
|        Software related to interfacing the BPM carrier board with a PC
|         via PCIe.
|
|-- embedded-sw (based on the original project by Alessandrio Rubini and others
     |            <http://www.ohwr.org/projects/wrpc-sw>):
     |   Embedded software that runs inside the LM32 softcore processor.
     |  
     |-- arch: 
     |       Architecture specific code, like linker scripts and boot code.
     |  
     |-- boards:  
     |       Board specific parameters and initialization.
     |  
     |-- dev:
     |       Device specific code, such as UART, GPIO and DMA interfaces
     |
     |-- include:
     |    |   General headers, mosly API device headers.
     |    |  
     |    |-- hw:
     |    |       Device specefic registers and strucutures. This defnitions
     |    |         are included by the more general headers located inside
     |    |         the "include" top directory.
     |    |  
     |    |-- memmgr:
     |            Memory pool for "dynamic" alocated memory. Code by
     |              by Eli Bendersky.
     |
     |-- lib: 
     |        Utilities and general functions, such as the memmgr subsystem
     |          and a printf-like function.
     |     
     |-- tests:    
     |        Folder dedicated to software testing.
     |
     |-- tools:     
              General tools for generating RAM loadable file by the firmware
                FPGA.

==========================================================

Cloning this repository:

This repository makes use of git submodules, located at 'hdl/ip_cores' folder:
	hdl/ip_cores/general-cores
	hdl/ip_cores/etherbone-core

To clone the whole repository use the following command:

	$ git clone --recursive git://github.com/lerwys/bpm-sw.git (read only)
	or
	$ git clone --recursive git@github.com:lerwys/bpm-sw.git (read+write)

For older versions of Git (<1.6.5), use the following:

	$ git clone git://github.com/lerwys/bpm-sw.git
	or
	$ git clone git@github.com:lerwys/bpm-sw.git

	$ git submodule init
	$ git submodule update

To update each submodule within this project use:

	$ git submodule foreach git rebase origin master
        
==========================================================

Simulation instructions:

  -> Go to a testbench directory. It must have a top manifest file:
    cd /hdl/testbench/path_to_testbench
  
  -> Run the following commands. You must have hdlmake2 command available
      in your PATH environment variable.
    
	-> Create the (ISim) simualation makefile

1 - hdlmake2 --make-isim

	-> Compile the project

2 - make

	-> Create the simulation executable elf file

3 - make fuse TOP_MODULE=<top_level_testbench_module_without_the_extension>

	-> Execute the simulation with GUI and aditional commands

4 - ./isim_proj -view wave.wcfg -tclbatch isim_cmd -gui
      
==========================================================

Synthesis instructions:

  -> Go to a syn directory. It must have a top manifest file:
    cd /hdl/top/path_to_top_design
  
  -> Run the following commands. You must have hdlmake2 command available
      in your PATH environment variable.
      
	-> Create the synthesis makefile and an ISE project

1 - hdlmake2 --make-ise --ise-proj

	-> Compile the source files locally

2 - make local

	-> Load the generated .bit file with iMPACT or other tool

3 - impact
==========================================================

Know Issues:

wb_fmc150/sim/: This folder containts behavioral simulation models
for memories (ROMs). However, the xilinx initialization file (.mif)
paths are absolute to a specific machine! You either have to change
the path to match your machine or figure a way to specifies a relative
path (specifiying only the name of the mif file does not work as the 
simulator is not called within this folder). Try a relative path based
on the simulation folder.
