Carefully managed revision control is an important aspect of electronic systems development. Revision control enables the developer to intelligently merge new contributions, analyze project history, and step backwards in time piece-by-piece when working to identify the root cause / introduction of a design defect (e.g., software / Verilog bug).
Although it may not be readily evident, FPGA development with Lattice Diamond is well suited for revision control due to the fact that many of the Diamond project source files (e.g., *.ldf, *.sty) are XML encoded text files, and the majority of the XML element leaf nodes are written on their own line (CR follows an end tag). This XML encoded text format is friendly for performing critical "diff" operations, where the revision control tool displays each difference, line-by-line, between two versions of the same file.
There are many good choices for revision control sysems, however due to our extensive experience with Linux and Web development, we have grown accustomed to Git.
On Windows 10, we use git for windows in a Windows 10 PowerShell, which provides a nice command line environment similar to what a Linux user might expect. We installed Git with the "Use Git from the Windows Command Prompt" and "Use Windows default console window" options. We accepted the other installation defaults.
On Linux and macOS, we typically use the distribution's supplied version of git. And, for a great generic Verilog IDE, we use Eclipse with the SVEditor plugin.
Note that switching back and forth between Windows and macOS/Linux platforms presents a line ending challenge for Git. This issue is discussed in this forum post.
Below we clone the Private Island project in a Windows 10 PowerShell under our folder c:\build>
PS C:\build> git clone https://mindchasers.com/repos/cgit.cgi/privateisland Cloning into 'privateisland'... PS C:\build> cd privateisland PS C:\build\privateisland> dir Directory: C:\build\privateisland Mode LastWriteTime Length Name ---- ------------- ------ ---- d----- 5/3/2019 1:15 PM boards d----- 5/3/2019 1:15 PM clarity d----- 5/3/2019 1:15 PM programming d----- 5/3/2019 1:15 PM source d----- 5/3/2019 1:15 PM testbenches -a---- 5/3/2019 1:15 PM 13 .gitattributes -a---- 5/3/2019 1:15 PM 263 .gitignore -a---- 5/3/2019 1:15 PM 11558 LICENSE -a---- 5/3/2019 1:15 PM 6182 privateisland.ldf -a---- 5/3/2019 1:15 PM 1120 README
Private Island Project Structure
Below we briefly describe the project structure:
PS C:\build\privateisland> tree Folder PATH listing for volume Windows Volume serial number is 8275-6EE4 C:. ├───boards │ └───darsena ├───clarity │ └───pcs │ ├───refclk0 │ ├───sgmii0 │ ├───sgmii1 │ ├───sgmii2 │ └───sgmii3 ├───programming ├───source └───testbenches
The top level folder contains the project file: privateisland.ldf. This is the file that you want to open inside of Diamond. To build the project, it's as simple as double clicking on the "Bitstream File" inside the Process tab (see figure below).
The boards folder contains the strategy (*.sty) and preferences (*.lpf) files for supported / ported boards, such as Darsena. We keep our Reveal files under boards for debugging but don't upstream them. However, example files may be included in the future.
The clarity folder contains the Clarity project for building the PCS/SERDES modules imported into the project (see notes about this below).
The programming folder contains the *.xcf files for performing operations like configuring the device via JTAG, programming the external ROM, and reading the device ID with the Lattice Programmer.
The source folder contains all the (open source) source (*.V) files
The testbenches folder contains the various test benchs for the project (many are under development and will soon be added to the project).
Managing the Project
When using revision control, one of the core concepts is to only store source files. These are the files that are required to regenerate the desired outputs (e.g., bit file) and all intermediate files in between. If you have been using Diamond, you probably realize that it creates many, many intermediate files, and we do not want to store these files in our repository.
The primary method for instructing Git to only include source files is to supply a ".gitignore" text file that lists file specifiers to ignore (one on each line). Note that many of the file types used by the Diamond tool suite are defined in an appendix of the Diamond User Guide. These file type definitions are driven by the file suffix (e.g., '.edf' is an EDIF file). Also included in the appendix is information on whether a particular file is required for generating a specific bitstream.
Provided below are the contents of the .gitignore file as of commit 5723ec1a. We are continuing to tweak this file, so please use it as starting point / template for your own use in creating your own development branch. If you err on the side of leaving out a particular suffix, then you may experience repo bloat with unnecessary files added to your repository. However, if you incorrectly add a specifier for a required source file type, then you may experience errors when going back in history and rebuilding the project.
.project .svproject syn_results archiv impl1 .recovery *_tcr.dir .*.ini *.asd *.asdb *.awb *.awc *.bak *.bak.* *.ccl *.cfg *.cmd *.cst *.htm *.html *.log *.rva *.rvs *.trc *.rvl *.ngd *.ngo *.tcl *.svf *.vhm *.xml *.zip *.vhd *~
Note that these file specifiers become a general rule. The user still has the option to include specific files in their own development branch that match one of these specifiers by using "git add -f <filename>". This may be useful when customizing a file that drives a third-party tool (e.g, a tcl file that is used with Synplify Pro) or Reveal debugger files (e.g., *.rvl, *.rva, & *.rvs).
Clarity (Lattice's IP Builder) deserves some additional explanation and care. It is used in Private Island to configure the PCS/SERDES blocks. From experimentation, we have found that the following files are necessary for both recreating the Clarity project and building the final bit file:
- pcs.sbx: Clarity project file
- *.v: generated Verilog. We keep these because we find it's necesary to tweak the generated Verilog (e.g., params to configure swapping of polarity)
- *.fdc: Synplify FPGA Design Contraint file contains a mapping of the Verilog to DCU/PCS lane
- *.lpc: Module Parameter Configuration File
Use of the Lattice Reveal logic analyzer with git can also be confusing. We have found that the Reveal project will not detect source code changes (e.g., git pull) while the Lattice project is open. Therefore, we either close the project between pulls / merges or we'll touch the source file and save it inside of Diamond. Either of these actions will cause Reveal to re-scan the source.
We'll continue to update this page as we continue to work with Git and Diamond for the Private Island project.