Gateware user guide
General notes on remote reprogramming
Types of gateware
There are three types of gateware:
- release
- provides the intended functionality of CONV-TTL-BLO
- golden
- fallback version in case MultiBoot fails
- test
- for long-term testing in the lab
Release projects in particular use the MultiBoot feature implemented on Xilinx Spartan-6 FPGAs. This means that there are two bitstreams on the CONV-TTL-BLO flash chips, a golden version and (normally) a latest release version.
Gateware version
The gateware version number can be read from the GWVERS field of the status register (SR) at address 0x4 for all gatewares except the communication test gateware (regtest). The GWVERS field (SR[7:0]) is defined as follows:
- SR[7:4] gateware version major number (e.g., 1.0, 2.0, 3.0, ..., 15.0)
- SR[3:0] gateware version minor number (e.g., 1.0, 1.1, 1.2, ..., 1.15)
Some possible values for the gateware version major number:
- 0 -- denotes golden gateware (v0.0, v0.1, etc.), the fallback bitstream in case of MultiBoot error
- 1/2/3 -- major releases of the application bistream after MultiBoot success
- 15 -- test gateware
Note that* since the regtest gateware contains a RAM filling up the entire addressing space, the GWVERS field does not contain a valid number. To identify a board programmed with this gateware, read the other fields of the SR. If they are all zeroes, the programmed gateware is a register test gateware.
Flash bitstreams memory map
* Address * | * Bitstream * |
---|---|
0x000000 | Header |
0x000044 | Golden |
0x170000 | MultiBoot |
See also the CONV-TTL-BLO User Guide.
Generating bitstreams for MultiBoot design
Preparing a bitstream containing the golden bitstream for MultiBoot
To prepare a bitstream containing both the golden and the release bitstream for download directly to the flash using, e.g. Xilinx iMPACT, use the catbstream.py script, which can be found under the software/* folder of the main repository.
Downloading the bitstream to the flash
Single board MultiBoot
To run MultiBoot on a single board, use the multiboot.py
script, which
can be found in the main
repository. This
script relies on a bin/
folder which contains the bitstreams to be
donwloaded to the flash. The user selects the operations he/she would
like performed (reading from flash, writing to it, issuing remote
reprogramming). The steps below show running the multiboot.py
script
after cloning the repository and downloading bitstream v3.0 to the
flash.
git clone --depth=1 git:https://www.ohwr.org/level-conversion/conv-ttl-blo.git
cd conv-ttl-blo/software/multiboot/
mkdir bin
wget https://www.ohwr.org/project/conv-ttl-blo-gw/uploads/7c934a5920464d1fbb7fa05cbceb7f29/conv_ttl_blo-v3.0.bin -O bin/conv_ttl_blo-v3.0.bin
./multiboot.py
The output of the script should be something like:
Successfully connected to some-elma
SysMon firmware v2.31
Slot no.: 1
CONV-TTL-BLO found in slot 1
Read config reg? (y/n) n
Read from flash? (y/n) n
Write to flash? (y/n) y
Are you sure?
(y/n) y
Which gateware would you like to program?
0 -> conv_ttl_blo-v3.0.bin
Enter your choice : 0
Selected gateware: conv_ttl_blo-v3.0.bin
Is this okay? (y/n) y
Issue IPROG?
(y/n) y
MultiBoot bitstream address: 0x170000
Writing bitstream to board in slot 1
0.81% (0x172f00)
For more information on the script itself, see the README file inside
the multiboot/
folder, as well as the code of the multiboot.py
script itself.
Mass MultiBoot
For running MultiBoot on multiple boards in a crate, there is a script
called mass-multiboot.py
. This script is CERN-specific and is used
to connect to an ELMA crate of the user's choice and run MultiBoot on
all cards found in the crate. While the script can be found in the
repository under the multiboot/
folder, the release version and the
one that should be run can be found at the following location on CERN's
AFS:
/acc/local/share/scripts
The script searches the following folder for bitstreams before presenting them to the user for selection. New release bitstreams should be placed in this folder:
/acc/local/share/firmware/conv-ttl-blo/
Run the script with the --help
option for information on how to use
it:
$ ssh cs-ccr-dev1
$ cd /acc/local/share/scripts
$ ./mass-multiboot.py --help
Usage: mass-multiboot.py [options] elma-crate board-id
Mandatory:
elma-crate Hostname or IP address of ELMA crate to address
board-id ID of board to program; must be one of
"TBLO" -> CONV-TTL-BLO
"T485" -> CONV-TTL-RS485
Options:
-h, --help show this help message and exit
-s, --start Start running programmed bitstream
-i IPROGADDR, --iprog=IPROGADDR
Run bitstream (IPROG) at a specific address and exit
or see the README file in the same directory:
ssh cs-ccr-dev1
cd /acc/local/share/scripts
more README
Theodor-Adrian Stana, Jan. 2015