README

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

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 buses, either a true hardware bus
|    |    |         or emulated software bus, through Ethernet.
|    |    |-- general-cores (fork from original project):
|    |            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 (BFMs),
|    |          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.
|    |
|    |-- drivers:
|    |        Linux Kernel code for device drivers
|    |
|    |-- include:
|    |        Header files for device structures and definitions
|    |
|    |-- lib:
|             Utilities and API functions exported by the drivers
|
|-- 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, mostly API device headers.
|    |    |
|    |    |-- hw:
|    |    |       Device specific registers and structures. This definitions
|    |    |         are included by the more general headers located inside
|    |    |         the "include" top directory.
|    |    |
|    |    |-- memmgr:
|    |            Memory pool for "dynamic" allocated memory.
|    |
|    |-- 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

  $ hdlmake2 --make-isim

Compile the project

  $ make

Create the simulation executable ELF file

  $ make fuse TOP_MODULE=<top_level_testbench_module_without_the_extension>

Execute the simulation with GUI and aditional commands

  $ ./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

  $ hdlmake2 --make-ise --ise-proj

Compile the source files locally

  $ make local

Load the generated .bit file with iMPACT or other tool

  $ impact

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

Known 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.