1  hostmot2-firmware: build assorted hostmot2 FPGA firmwares automatically
 2  
 3  == Overview ==
 4  
 5  This package includes the hostmot2 source files along with Makefiles and
 6  other scripts to automatically build all the desired variants of the
 7  firmwares.
 8  
 9  It requires the no-cost version of Xilinx ISE.  I build with ISE 9.2.  This
10  version supports all FPGAs on Mesa cards with the exception of the 3x20-2M.
11  Newer versions appear to work, but with caveats (see below)
12  
13  It also requires ghdl for building PIN and xml files.  The PIN file
14  format is intended to be human readable (not machine readable) so it is
15  not a requirement that it exactly match the format of existing PIN
16  files.  There is also an experimental xml description format.
17  
18  == ISE Version Requirements
19  
20  Refer to `cards.py` for information about required ISE versions for
21  particular cards.  Currently, by installing ISE 13.4 and ISE 9.2, firmware
22  can be built for all supported cards.
23  
24  === Obtaining ISE 9.2 WebPack ===
25  
26  Xilinx still offers older versions of ISE free of charge.  At the time
27  of writing, the location is
28      http://www.xilinx.com/webpack/classics/wpclassic/index.htm
29  and can also be reached from the xilinx.com front page by going to
30  "Products & Services", "Design Tools", "Logic Design Tools", "ISE
31  Classics", "Previous versions of ISE WebPack".
32  
33  == Building ==
34  
35  If necessary, create a set of symlinks to the required versions of ise.  For
36  32-bit versions up to 13.3 installed to /opt, settings will generally be found
37  automatically.  If they are not, you can create symlinks e.g.,
38      settings9.sh -> /opt/Xilinx19/settings32.sh
39      settings13.sh -> /opt/Xilinx13.4/settings32.sh
40  
41  To build all bitfiles, pinfiles, and xmlfiles:
42      make -j4                   # -j setting depends on RAM and # CPU cores
43  On my system (quad core AMD Phenom 9600) building the full set of
44  firmwares took about 75 minutes wall time with the -j4 setting shown
45  above.
46  
47  To build just a subset of firmwares, create a file `firmwares-local.txt` to list the firmware(s) you want to build.
48  This list is used instead of the list in `firmwares.txt`.
49  The first word in each line specifies the hostmot2 card, and the remaining words specify the pinfiles.
50  For example, to build just the 'SV12' firmware for the '5i23' card, put just this line in 'firmwares-local.txt':
51      i23 SV12
52  
53  To build Debian packages:
54      debian/gencontrol
55      export MAKEFLAGS=-j4 dpkg-buildpackage
56                                 # -j setting depends on RAM and # CPU cores
57  
58  To build tar packages (must be in a git checkout):
59      make -j4                   # -j setting depends on RAM and # CPU cores
60      make dist
61      # or make dist-force if your working tree is dirty
62  
63  
64  
65  == Testing ==
66  
67  A representative firmware for each supported board type has been tested:
68   * 5i20, 5i22-1M, 5i23 (PCI)
69   * 7i43-400 (EPP)
70   * 3x20-1M (PCI-Express)
71   * 4i65, 4i68 (PC104+)
72  The 5i22-1.5M and 7i43-200 are not tested, but are expected to work.
73  
74  
75  == Incorporating new upstream source ==
76  
77  Primary development of the hostmot2 fpga firmware is done by Mesa Electronics, who releases source in .zip format.
78  This repository integrates that source with a Linux-centric build infrastructure to produce Debian packages.
79  When incorporating upstream changes from Mesa, the following procedure should be used:
80   1. Put the new source code release on the "upstream" branch as a single large commit
81   1. Merge upstream and master into a (possibly local) testing branch
82   1. Make additional commits to add new card support, adjust for changed filenames, etc
83   1. Test on a representative set of boards
84   1. When the result of testing is satisfactory, merge to master branch.  Push new master and upstream branches to git.linuxcnc.org.
85  
86  In the rare cases that we make a change to a .vhd, .pin, or other file that comes from Mesa, this strategy with an upstream branch lets us retain that change
87  (or have it appear as a merge conflict, if it cannot be automatically applied),
88  instead of losing it when we receive a new set of base source files.