\input texinfo    @c -*-texinfo-*-
%
% fine-delay.in - main file for the documentation
%
%%%%

%------------------------------------------------------------------------------
%
%                         NOTE FOR THE UNAWARE USER
%                         =========================
%
%    This file is a texinfo source. It isn't the binary file of some strange
%    editor of mine. If you want ASCII, you should "make fine-delay.txt".
%
%------------------------------------------------------------------------------

%
% This is not a conventional info file...
% I use three extra features:
%   - The '%' as a comment marker, if at beginning of line ("\%" -> "%")
%   - leading blanks are allowed (this is something I can't live without)
%   - braces are automatically escaped when they appear in example blocks
%

@comment %**start of header
@documentlanguage en
@documentencoding UTF-8
@setfilename svec-firmware-manual.info
@settitle svec-firmware-manual
@iftex
@afourpaper
@end iftex
@paragraphindent 3
@comment %**end of header

@setchapternewpage off

@set update-month January 2014

@finalout

@titlepage
@title Standard SVEC firmware
@subtitle Programmer's manual
@author CERN BE-CO-HT / Tomasz Włostowski, 16.01.2014
@end titlepage
@headings single

@iftex
@contents
@end iftex

@c ##########################################################################
@node Top
@chapter Introduction

This document describes the default bitstreams that come preloaded with every SVEC card. As there are two FPGAs on the SVEC, there are two default bitstreams:
@itemize
@item @b{Bootloader bitstream}, residing in the System FPGA whose role is to start up the Application FPGA,
@item @b{Golden bitstream}, residing in the Application FPGA, which allows the SVEC device driver to enumerate the mezzanines.
@end itemize

@chapter The Bootloader

The System FPGA bootloader allows to boot the Application FPGA from the VME bus or from the onboard Flash memory and reprogram both the System and Application bitstreams in the flash via VME (see @ref{fig:boot_modes}). The boot process goes as follows:
@itemize
@item Power up,
@item SFPGA checks for presence of a valid bitstream file for the Application FPGA in the Flash memory,
@item If a valid bitstream has been found, the AFPGA is initialized with it,
@item if not, the Bootloader enters passive mode. Upon reception of a boot sequence, if gives access to the Flash for the host or lets it program the AFPGA directly.
@end itemize

@float Figure,fig:boot_modes
@center @image{drawings/boot_block, 12cm,,,.pdf}
@caption{Boot modes of the SVEC card.}
@end float

@section Bootloader versions

There are two versions of the bootloader in use:
@itemize 
@item The new one (a.k.a. version 2) which supports everything described in this manual.
@item The old one (version 1) which only allows booting the Application FPGA via VME (no flash support). This version of the bootloader has been programmed in older SVEC cards. If the VME flasher (@code{svec-flasher}) tool is unable to detect the flash memory, you're likely running the old bootloader.
@end itemize

The new version is software-compatible with the old one, there is no need to update any drivers. The register description applies to both versions, except that for the version 1, the Flash Access Register (@code{FAR}) is not functional.

@section VME Interface
The bootloader core supports only 32-bit data CR/CSR accesses from/to address range @code{0x70000} - @code{0x70020}, allowing for plug&play reprogramming of the cards only knowing their physical slot locations. All other transfers are ignored. The base address is @code{0x70000}, and corresponds to the @code{CSR} register. When the card is powered up, the VME interface stays in passive mode, monitoring VME accesses without ACKing them. This is to prevent conflicts with the CR/CSR space of the VME core in the Application FPGA. 

@section Entering bootloader mode
In order to enter the bootloader, one needs to write the magic sequence of 8 following transfers: @code{0xde}, @code{0xad}, @code{0xbe}, @code{0xef}, @code{0xca}, @code{0xfe}, @code{0xba}, @code{0xbe} to the @code{BTRIGR} register (for register definitions, @pxref{System FPGA Register Map}).

In order to check if the bootloader has been activated, read the @code{IDR} register. It should be equal to @code{SVEC} ASCII string encoded in HEX. Any other value indicates that the boot trigger sequence was not correctly recognized, the System FPGA is unprogrammed, the geographical address of the card is wrong or that the card itself is faulty.

@b{Note 1:} Triggering bootloader mode causes automatic reset (un-programming) of the Application FPGA.

@b{Note 2:} Since the bootloader core supports only 32-bit transfers, one must extend the magic values with zeroes (e.g. @code{0x000000de}, etc.) and write full 32-bit words. Attempts to write the magic sequence as single bytes (D8 transfer mode) will be ignored.

@b{Note 3:} Trigger sequence must not be interleaved with other accesses to the bootloader address range of the same card.

@b{Note 4:} Write operations to @code{BTRIGR} register while the bootloader is in passive mode will not be acknowledged on the VME bus and may sometimes cause bus errors to be reported by the host VME driver. They are not harmful, though. 

@section Programming the AFPGA
Programming the Application FPGA directly via VME involves the following steps:
@itemize
@item Reset the Xilinx Passive Serial boot interface by writing the @code{CSR.SWRST} bit,
@item Set download speed by writing the @code{CSR.CLKDIV} field. Default value is @code{1},
@item Write the @code{CSR.START} bit and set endianness via the @code{CSR.MSBF} bit,
@item Write the bitstream to the FIFO registers, observing FIFO full/empty status. The last transfer should have @code{FIFO_R1.XLAST} bit set to 1,
@item Wait for assertion of @code{CSR.DONE}. @code{CSR.ERROR} bit indicates a problem during configuration (most likely, an invalid bitstream),
@item Exit bootloader mode by writing 1 to @code{CSR.EXIT} bit.
@end itemize

A code example is available in the repository (@pxref{repo_link,,2}). Successful firmware download to the Application FPGA is indicated by turning on the ``AFPGA DONE'' LED in the middle of the PCB.

@section Programming the Flash
The SFPGA also allows raw access to the Flash memory (M25P128) via the @code{FAR} register. The code below shows how to execute a single SPI transaction (command + N data bytes). 

Low-level details about programming M25Pxxx series Flash memories can be found in their datasheets (@pxref{m25p_datasheet,,1}). A simple VME flasher is provided in @code{software/vme-flasher} directory.

@b{Note 1:} It is advised to protect the region of the flash containing the system FPGA bitstream from being accidentally overwritten, as this will result in rendering the card unusable and will require re-programming the flash via JTAG. Details on memory protection can be found in the M25P series datasheet.

@b{Note 2:} The freshly-programmed bitstreams will be loaded into the FPGAs after power-cycling the card. In order to avoid the power cycle, one can boot the Application FPGA directly using the same bitstream.

@section Flash memory organization

The flash memory of the SVEC contains 16 Megabytes of data, that is 65536 pages of 256 bytes. The first 6 MBs are used for bitstream storage. The flash format is compatible with the SDB filesystem, with the SDB descriptor table located at offset @code{0x600000}. Locations of the bitstreams are fixed to:
@itemize
@item @code{0}: Raw bitstream for the System FPGA (up to 1 MB).
@item @code{0x100000}: Raw bitstream for the Application FPGA (up to 5 MB).
@end itemize

An example script for building the default flash filesystem (containg the bootloader and golden bitstreams) is located in the @code{software/sdb-flash} subdirectory in the SVEC project's repository(@pxref{repo_link,,2}). Presence of the SDB descriptor table at @code{0x600000} is checked by the bootloader to prevent booting up from a corrupted or unprogrammed flash. 

@b{Note:} Both bitstreams must be in raw (@code{.bin} file extension) format. @code{.bit}, @code{.mcs}, @code{.xsvf} and other formats will not work. 

@page
@chapter The Golden Bitstream
The SVEC Application FPGA golden bitstream is loaded by the SVEC driver during its startup. Its purpose is to:
@itemize
@item Query the board's serial number.
@item Check the presence of the FMC mezzanines.
@item Read out their @math{I^2C} identification EEPROMs.
@end itemize
The bitstream does not drive any of the mezzanine user/clock pins to protect from electrical damage resulting from mismatched I/O standards.

@section Block diagram

The bitstream encompasses @math{I^2C}, OneWire and GPIO modules from the @code{general-cores} library. For further details, refer to the library's manual.

@float Figure,fig:block
@center @image{drawings/golden_block, 15cm,,,.pdf}
@caption{Block diagram of the SVEC golden gateware.}
@end float

Presence detection is done by reading out the @code{PRSNT} lines (active low) through the GPIO port. EEPROM readout is performed via the two @math{I^2C} masters. The board serial number
is equal to the serial number of the DS18B20U+ temperature sensor, accessible via the OneWire master. The clock freqency for @math{I^2C} and OneWire dividers calculation is 62.5 MHz. 

@section Memory map

@b{Note:} Please do not hardcode the base addresses of the cores, query them from the SDB descriptor. The SDB address of @code{0x0} is guaranteed to stay constant.
Only A32/A24/D32/CSR address modifiers are supported.

@multitable @columnfractions .20 .10 .15 .65
@headitem Core @tab Base address @tab Library @tab Description
@item @code{sdb_rom} @tab @code{0x0} @tab @code{general-cores} @tab SDB descriptor.
@item @code{xwb_i2c_master} @tab @code{0x10000} @tab @code{general-cores} @tab I2C Master for accessing FMC 1 identification EEPROM.
@item @code{xwb_i2c_master} @tab @code{0x11000} @tab @code{general-cores} @tab I2C Master for accessing FMC 2 identification EEPROM.
@item @code{xwb_onewire_master} @tab @code{0x12000} @tab @code{general-cores} @tab OneWire Master for accessing temperature sensor/serial ID.
@item @code{xwb_gpio_port} @tab @code{0x13000} @tab @code{general-cores} @tab GPIO port for accessing FMC1/2 presence lines.
@end multitable



@macro regsection{name}
@section \name\
@end macro

@page
@chapter Flashing the SVEC
@section Application FPGA Flash programming through VME

The SVEC Application FPGA can be programmed with the @code{svec-flasher} tool, located in @code{software/vme-flasher} subdirectory of the SVEC project repository. It requires a @code{.bin} format bitstream, that can be generated by Xilinx ISE by selecting ``Generate binary configuration file'' in @i{Generate Programming File} options.

The flasher requires the slot number as the first argument and the file with the bitstream as the second, just like in the example below:
@example
# ./svec-flasher.L865 12 /lib/firmware/fmc/svec-golden.bin 
Programming the Application FPGA flash with bitstream /lib/firmware/fmc/svec-golden.bin.
Programming page 7651/7651.   
Verification...
Programming page 0/0.   
Verification...
Programming OK.
@end example

@b{Note 1:} Before programming the flash, please unload the SVEC kernel driver:
@example
# rmmod svec
@end example
@b{Note 2:} The flasher must be run as root.
@b{Note 3:} The card must be rebooted for the new bitstream to be loaded to the Application FPGA.

@section Updating the bootloader

Certain older SVEC cards have been shipped with the first version of the bootloader that does not support booting the AFPGA from the Flash memory. In order to use from the VME Flasher, an update is necessary. The procedure goes as follows:
@itemize
@item Download the updated bootloader @code{svec-bootloader-v2-20140116.mcs} from @uref{http://www.ohwr.org/projects/svec/files}.
@item Connect Xilinx JTAG programmer to the JTAG connector of the card to be updated.
@item Launch ISE iMPACT.
@item Double-Click ``Boundary Scan'' in the left pane (``iMPACT flows'').
@item Open the right-click menu in the main work area and select ``Initialize chain'' or press Ctrl+I.
@item Right click on the ``SPI/BPI ?'' box above the ``xc6slx9'' FPGA and select ``Add SPI/BPI Flash''.
@item Pick the @code{svec-bootloader-v2-20140116.mcs} file.
@item Select flash type: SPI PROM, M25P128, data width: 1.
@item Right click on the ``FLASH'' chip above the ``xc6slx9'' and select ``Program''. Select the ``Verify'' option and click OK.
@item If everything went fine, ``Programming succeeded'' message will appear.
@item Reboot the VME crate to use the new bootloader.
@end itemize

@b{Note:} Updating the bootloader does not require updating the drivers, as it is backwards-compatible.

@section Application FPGA Flash programming through JTAG

This method of programming may be useful during factory JTAG programming of SVECs, when both the bootloader and the application bitstream need to be loaded simultaneously. It requires a special flash image that contains both the bootloader and application bitstreams along with some SDB filesystem structures that allow the bootloader to correctly load the AFPGA file.

Preparing the flash image is straightforward:
@itemize
@item Copy your AFPGA bitstream (@code{.bin} format) to @code{software/sdb-flasher/fs/afpga.bin}.
@item Run the script: @code{software/sdb-flasher/build.sh}. The script will produce the file called @code{image.mcs}.
@item Program the Flash (@code{image.mcs}) via iMPACT, using the procedure described in the previous section.
@end itemize

The script requires the @code{gensdbfs} utility. The easiest way to install it is to:
@itemize
@item Clone the @code{fpga-config-space} repository: 
@example
git clone git://ohwr.org/hdl-core-lib/fpga-config-space.git.
@end example
@item Compile it: 
@example
cd fpga-config-space/sdbfs/lib
make
cd ../userspace
make
@end example
@item Copy @code{gensdbfs} binary to a directory within the @code{PATH}.
@end itemize

@page
@chapter References
@enumerate
@anchor{m25p_datasheet}
@item @uref{http://www.micron.com/parts/nor-flash/serial-nor-flash/m25p128-vme6gb} - M25P series SPI Flash memory datasheet
@anchor{repo_link}
@item @uref{http://www.ohwr.org/projects/svec/repository/} - Git repository containing this document's sources and revision history (@code{doc} subdirectory) and bootloading code examples (@code{software/sveclib} subdirectory).
@end enumerate
@page
@appendix System FPGA register map
@b{Note:} All registers are 32 bits-wide. Unaligned accesses, or accesses with data width other than 32 bits are @b{ignored}. Bits not specified in tables are not used (writes are ignored, reads return undefined values).

@anchor{System FPGA Register Map}
   @include svec_xloader.in

@appendix Important File Locations
All necessary firmware files are located in the ``Files'' section of the SVEC project:
@uref{http://www.ohwr.org/projects/svec/files}. This is the @b{only} place where official binaries are held. We will not provide support for bootloader/golden bitstreams downloaded elsewhere.

@itemize
@item @code{svec-bootloader-v2-20140116.mcs}: the V2 bootloader, MCS file for flashing using Xilinx tools
@item @code{svec-bootloader-v2-20140116.bin}: the V2 bootloader, binary file for XC3Sprog and PTS factory flasher.
@item @code{svec-bootloader-v2-20140116.bit}: the V2 bootloader, Xilinx BIT file.
@item @code{svec-golden-20140116.bin}: the golden bitstream.
@end itemize
@bye

