<!--
SPDX-FileCopyrightText: 2023 CERN

SPDX-License-Identifier: CC-BY-SA-4.0+
-->

MEN A25 SBC PCIe-VME Bridge Gateware
====================================

This projects contains files required to build the PCIe to VME bridge gateware
for the MEN A25 VME SBC.

How to generate the FPGA bitstream
----------------------------------

1. Fetch all git submodules with ``git submodule update --init``.
2. Make sure you have [HDLmake](https://hdlmake.readthedocs.io) version
**greater** than 3.3 (it should include at least commit ``3ac2e4e``, if unsure
go for latest commit on the master branch).
3. Make sure you have Altera Quartus 16.0 installed, along with support for the
   Cyclone IV GX FPGA family.
4. Enter the ``hdl/syn`` folder and run ``hdlmake`` (make sure that Altera
   Quartus binaries are in your system path beforehand).
5. At this point you can either simply run ``make`` to build the project and
   generate the FPGA bitstream, or ``make project`` to only generate the Altera
   Quartus project files (``A25_top.qsf`` and ``A25_top.qpf``) which you can
   then open in the Quartus GUI and continue the build process in there.
6. Either way, if the process is successful, new files with name
   ``16A025-00_MM_mm`` will be generated in ``hdl/syn/fpga_files``. You should
   **only** use those files for programming the FPGA. Please note that the
   ``hdl/syn/A25_top.bin`` is **not** the right file, it will lead to
   a programmed FPGA with a missing bitstream header.

How to set a new FPGA revision
------------------------------

The process inherited from MEN is based on a tool called Chameleon, which
generates an Intel hex file with the contents of the ROM that will be later
accessible through Wishbone. This ROM contains version information, addresses of
peripherals, etc.

When you need to bump the FPGA revision, please follow these steps:

1. You first need to compile the Chameleon tool (if not already done). To do
   this, go to ``software/tools/16t001-00_src/Source`` and run ``create.sh``
   (``create_exe.bat`` on Windows). This will build the binary and install it
   under ``software/tools/16t001-00_bin/Bin`` (ignored by git). The tool is a
   Perl-based compiled script so you will need a number of Perl-related packages
   installed to be able to build it. The exact details are OS-dependent. As an
   indication, on Archlinux the following packages were required (tested in
   August 2023):
    + perl-par-packer
    + perl-getopt-mixed (AUR)
    + perl-xml-sax-expat-incremental (AUR)
    + perl-spreadsheet-parseexcel (AUR)
    + perl-spreadsheet-writeexcel (AUR)
2. Edit ``hdl/top/chameleon_V2.xls`` in order to set new revision (Page
   "Content", minor revision in C8, major revision in C7) and close xls.
3. call ``hdl/top/cham2.sh`` (or ``cham2.bat`` on Windows) for hex file generation.
4. Edit ``hdl/syn/scripts/gen_programming_files.tcl`` and change programming
   file name to new revision in variable PROJECT_RELEASE_NAM "16A025-00_MM_mm".
5. All set, proceed with building the project and producing the FPGA bitstream.


Flashing using ht-flasher
-------------------------

The bitstreams are stored in a M25P32 flash (4MB).  Although the
bitstream image is slightly less than 1MB, the system is supposed to
contain only 2 images.

At offset 0, the factory image is stored in the raw format (the .rbf,
without any header).  At power-up, the fpga will automatically load
this image.  This is the recue image and it shouldn't be reflashed in
operation.  The bitstream will automatically load the application
image unless an error happened before (like invalid application
image).

At offset 0x200000 (2MB), the application image is stored with an
header (256B).  By default, this is the bitstream used.

Using ht-flasher (and we assume the pci slot is 03:00), you can check
which image is loaded:

```
> ht-flasher -a mena25 -d 03:00 -i
control:      00000000
data:         ffffffff
board status: 00000001
 image: application
boot-addr:    00200100
flash id:     00000015 (15=M25P32 - 4MB)
```

You can flash the application bitstream using the `-w` option.

You can reconfigure the FPGA using the `-b` option.  But you then need
to rescan the pci device.

You can display the FPGA header using the `-H` option.  This is useful
to display the version and date:

```
> sudo ht-flasher -a mena25 -d 03:00 -o 0x200000 -H
magic at 0x00300000: 52d4268e
filename: './A25_top                   ', fpga: 'EP4CGX30        '
size: 841044
date: 2023-12-13 17:16
board type: '16A025-00       '
```

In case of invalid bitstream, the FPGA will fallback to the factory bitstream:

```
>sudo ht-flasher -a mena25 -d 03:00 -i
control:      00000000
data:         ffffffff
board status: 00000022
 image: fallback after error
boot-addr:    00000000
flash id:     00000015 (15=M25P32 - 4MB)
```
