Subversion Repositories wbicapetwo

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% Filename: 	spec.tex
%%
%% Project:	Wishbone to ICAPE2 interface conversion
%%
%% Purpose:	This LaTeX file contains all of the documentation/description
%%		currently provided with this FPGA Real-time Clock Core.
%%		It's not nearly as interesting as the PDF file it creates,
%%		so I'd recommend reading that before diving into this file.
%%		You should be able to find the PDF file in the SVN distribution
%%		together with this PDF file and a copy of the GPL-3.0 license
%%		this file is distributed under.  If not, just type 'make'
%%		in the doc directory and it (should) build without a problem.
%%		
%%
%% Creator:	Dan Gisselquist
%%		Gisselquist Technology, LLC
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% Copyright (C) 2015, Gisselquist Technology, LLC
%%
%% This program is free software (firmware): you can redistribute it and/or
%% modify it under the terms of  the GNU General Public License as published
%% by the Free Software Foundation, either version 3 of the License, or (at
%% your option) any later version.
%%
%% This program is distributed in the hope that it will be useful, but WITHOUT
%% ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY or
%% FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
%% for more details.
%%
%% You should have received a copy of the GNU General Public License along
%% with this program.  (It's in the $(ROOT)/doc directory, run make with no
%% target there if the PDF file isn't present.)  If not, see
%% <http://www.gnu.org/licenses/> for a copy.
%%
%% License:	GPL, v3, as defined and found on www.gnu.org,
%%		http://www.gnu.org/licenses/gpl.html
%%
%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\documentclass{gqtekspec}
\project{ICAPE2 Access via Wishbone}
\title{Specification}
\author{Dan Gisselquist, Ph.D.}
\email{dgisselq (at) opencores.org}
\revision{Rev.~0.1}
\begin{document}
\pagestyle{gqtekspecplain}
\titlepage
\begin{license}
Copyright (C) \theyear\today, Gisselquist Technology, LLC
 
This project is free software (firmware): you can redistribute it and/or
modify it under the terms of  the GNU General Public License as published
by the Free Software Foundation, either version 3 of the License, or (at
your option) any later version.
 
This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
for more details.
 
You should have received a copy of the GNU General Public License along
with this program.  If not, see \hbox{<http://www.gnu.org/licenses/>} for a
copy.
\end{license}
\begin{revisionhistory}
0.2 & 4/22/2016 & Gisselquist & Minor Updates \\\hline
0.1 & 5/25/2015 & Gisselquist & First Draft \\\hline
\end{revisionhistory}
% Revision History
% Table of Contents, named Contents
\tableofcontents
% \listoffigures
\listoftables
\begin{preface}
My thanks to those helpers on the Xilinx Forum who helped me through the final
step in getting this working.
\end{preface}
 
\chapter{Introduction}
\pagenumbering{arabic}
\setcounter{page}{1}
 
This core makes the ICAPE2 FPGA configuration registers available to be read
or written from a wishbone bus.  As Xilinx's documentation of this capability
leaves a bit to be desired, I have put this file together to help document
what works.
 
The interface itself is very valuable for a couple of purposes---from my humble
and personal perspective.  The first is the user configurable watchdog timer
which can be used to automatically reset an FPGA after it locks up.  The second
is the warm boot start capability, which makes it possible to create a fall
back configuration image and test it without compromising the ability of the
FPGA to be started in a known good image.  The third valuable capability is that
of commanding a reconfiguration.  All of these capabilities are available
through this interface.  Further details are available from Xilinx's ``7-Series
FPGAs Configuration'' User Guide\footnote{For the Spartan, further details are
available in the ``Spartan--6 FPGA Coniguration'' User Guide}.
 
This introduction is the first chapter.  Beyond this introduction, most
of the capabilities are documented elsewhere.  Hence, the register chapter
will be omitted and the reader will be gently pointed to the User's Guide.
This leaves the Wishbone chapter and the I/O Port's chapter which follow.
 
As always, write me if you have any questions or problems.
 
\chapter{Architecture}\label{chap:arch}
 
If I understand correctly, every one of Xilinx's 7--Series FPGA's contains
two ICAPE2 interface modules.  These modules allow user logic to communicate
with the configuration interface of the chip.  This interface, however, isn't
well documented.  According to the User's Guide, it matches the SelectMAP
interface, yet in practice \ldots it doesn't.  It may come close, but the
timing and interface requirements of the SelectMAP aren't really the same as the
ICAPE2 port.
 
This core encapsulates the difficulty of matching that interface.  Register
addresses match those in the User's Guide, as do register definitions.
 
\chapter{Operation}\label{chap:ops}
 
Realistically, this is better documented by Xilinx than anything you will find
here.  Still, two examples might be worthwhile.
 
First, consider the warm boot reload operation.  To do this, write the address
in configuration memory of an FPGA image to the warm boot start address
(WBSTAR).  In this case, that is address 5'h10 within this interface.  A second
write to the configuration command address (CMD), 5'h4 in this interface, will
issue the IPROG command to the FPGA and cause it to configure itself from the
address you just gave it.  You can see this from C pseudo code in
Fig.~\ref{fig:warmboot}.
\begin{figure}\begin{center}\begin{tabbing}
{\tt warmboot(uint32 address) \{} \\
\hbox to 0.25in{}\={\tt uint32\_t *icape = (volatile uint32\_t *)0x{\em <ICAPE port address>};}\\
 \>{\tt icape[16] = address};\\
 \>{\tt icape[4] = 15};\\
 \>{\em // FPGA is now reconfiguring itself from the new address}\\
 \>{\em // If executed on an FPGA, this routine will never return.}\\
{\tt \}}
\end{tabbing}
\caption{Series--7 ICAPE2 Usage}\label{fig:warmboot}
\end{center}\end{figure}
 
There, wasn't that simple?
 
We could do it for the Spartan--6 as well, as shown in Fig.~\ref{fig:sp6boot}.
\begin{figure}\begin{center}\begin{tabbing}
{\tt warmboot(uint32 address) \{} \\
\hbox to 0.25in{}\={\tt uint32\_t *icape6 = (volatile uint32\_t *)0x{\em <ICAPE port address>};}\\
 \>{\tt icape6[13] = (address<<2)\&0x0ffff;}\\
 \>{\tt icape6[14] = ((address>>14)\&0x0ff)|((0x03)<<8);}\\
 \>{\tt icape6[4] = 14;}\\
 \>{\em // The Spartan--6 is now reconfiguring itself from the new address.}\\
 \>{\em // If executed from a softcore internal to a Spartan--6, this routine}\\
 \>{\em // will never return.}\\
{\tt \}}
\end{tabbing}
\caption{Spartan--6 ICAPE Usage}\label{fig:sp6boot}
\end{center}\end{figure}
 
Now I can, from the comfort of my home, reconfigure an FPGA in my office without
needing to press the power button or connect to a JTAG cable.  Not bad, no?
 
\iffalse
\chapter{Configuration Registers}\label{chap:registers}
% Tbl.~\ref{tbl:wishbone}
 
% 7 Series
\begin{table}[htbp]\begin{center}\hline
\begin{tabular}{|p{0.75in}|p{0.75in}|p{0.5in}|p{2.875in}|}\hline
\rowcolor[gray]{0.85} Name  & Address & Access & Description \\\hline\hline
CRC     & {\tt 0x00} & R/W & CRC Register \\\hline
FAR     & {\tt 0x01} & R/W & Frame Address Register\\\hline
FDRI    & {\tt 0x02} &   W & Frame Data Register, Input Register (write configuration data)\\\hline
FDRO    & {\tt 0x03} & R   & Frame Data Register, Output Register (read configuration data)\\\hline
CMD     & {\tt 0x04} & R/W & Command Register\\\hline
CTL0    & {\tt 0x05} & R/W & Control Register 0\\\hline
MASK    & {\tt 0x06} & R/W & Masking Register for CTL0 and CTL1\\\hline
STAT    & {\tt 0x07} & R   & Status Register\\\hline
LOUT    & {\tt 0x08} &   W & Legacy Output Register for Daisy Chain\\\hline
COR0    & {\tt 0x09} & R/W & Configuration Option Register 0\\\hline
MFWR    & {\tt 0x0a} &   W & Multiple Frame Write Register \\\hline
CBC     & {\tt 0x0b} &   W & Initial CBC Value Register \\\hline
IDCODE  & {\tt 0x0c} & R/W & Device ID Register\\\hline
AXSS    & {\tt 0x0d} & R/W & User Access Register \\\hline
COR1    & {\tt 0x0e} & R/W & Configuration Options Register 1\\\hline
WBSTAR  & {\tt 0x10} & R/W & Warm boot Start Addres Register \\\hline
TIMER   & {\tt 0x11} & R/W & Watchdog Timer Register\\\hline
BOOTSTS & {\tt 0x16} & R   & Boot History Status Register \\\hline
CTL1    & {\tt 0x18} & R/W & Control Register 1 \\\hline
BSPI    & {\tt 0x1f} & R/W & BPI/SPI Configuration Options Register\\\hline
\end{tabular}
\caption{7--Series Configuration Register Addresses}\label{tbl:7addrs}
\end{center}\end{table}
 
% SPARTAN-6 series
\begin{table}[htbp]\begin{center}\hline
\begin{tabular}
\begin{tabular}{|p{0.75in}|p{0.75in}|p{0.5in}|p{2.875in}|}\hline
\rowcolor[gray]{0.85} Name  & Address & Access & Description \\\hline\hline
CRC          & {\tt 0x00} &   W & Cyclic Redundancy Check\\\hline
FAR\_MAJ     & {\tt 0x01} &   W & Frame Address Register Block and Major\\\hline
FAR\_MIN     & {\tt 0x02} &   W & Frame Address Register Minor\\\hline
FDRI         & {\tt 0x03} &   W & Frame Data Input\\\hline
FDRO         & {\tt 0x04} & R   & Frame Data Output\\\hline
CMD          & {\tt 0x05} & R/W & Command \\\hline
CTL          & {\tt 0x06} & R/W & Control \\\hline
MASK         & {\tt 0x07} & R/W & Control Mask\\\hline
STAT         & {\tt 0x08} & R   & Status \\\hline
LOUT         & {\tt 0x09} &   W & Legacy Output for Daisy Chain\\\hline
COR1         & {\tt 0x0a} & R/W & Configuration Option 1\\\hline
COR2         & {\tt 0x0b} & R/W & Configuration Option 2\\\hline
PWRDN\_REG   & {\tt 0x0c} & R/W & Power Down Option Register\\\hline
FLR          & {\tt 0x0d} &   W & Frame Length Register\\\hline
IDCODE       & {\tt 0x0e} & R/W & Product IDCODE\\\hline
CWDT         & {\tt 0x0f} & R/W & Configuration Watchdog Timer\\\hline
HC\_OPT\_REG & {\tt 0x10} & R/W & House Clean Option Register\\\hline
CSBO         & {\tt 0x12} &   W & CSB Output for Parallel Daisy Chaining\\\hline
GENERAL1     & {\tt 0x13} & R/W & Power up Self-Test or Loadable Program Address\\\hline
GENERAL2     & {\tt 0x14} & R/W & Power up Self-Test or Loadable Program Address and new SPI opcode\\\hline
GENERAL3     & {\tt 0x15} & R/W & Golden Bitstream Address\\\hline
GENERAL4     & {\tt 0x16} & R/W & Golden Bitstream Address and new SPI Opcode\\\hline
GENERAL5     & {\tt 0x17} & R/W & User-defined register for fail-safe scheme\\\hline
MODE\_REG    & {\tt 0x18} & R/W & Reboot mode\\\hline
PU\_GWE      & {\tt 0x19} &   W & GWE cycle during wake-up from suspend\\\hline
PU\_GTS      & {\tt 0x1a} &   W & GTS cycle during wake-up from suspend\\\hline
MFWR         & {\tt 0x1b} &   W & Multi-frame write register\\\hline
CCLK\_FREQ   & {\tt 0x1c} &   W & CCLK frequency select for master mode\\\hline
SEU\_OPT     & {\tt 0x1d} & R/W & SEU frequency, enable and status\\\hline
EXP\_SIGN    & {\tt 0x1e} & R/W & Expected readback signature for SEU detection\\\hline
RDBK\_SIGN   & {\tt 0x1f} &   W & Readback signature for readback command and SEU\\\hline
BOOTSTS      & {\tt 0x20} & R   & Boot History Register\\\hline
EYE\_MASK    & {\tt 0x21} & R/W & Mask pins for Multi--Pin Wake-up\\\hline
CBC\_REG     & {\tt 0x22} &   W & Initial CBC Value Register\\\hline
\end{tabular}
\caption{Spartan--6 Configuration Register Addresses}\label{tbl:6addrs}
\end{center}\end{table}
 
% icape->general1 = (fpgaddr<<2);
% icape->general2 = ((fpgaddr>>14)&0x0ff)|((0x03)<<8);
% icape->cmd = 0x0e	// IPROG
\fi
 
\chapter{Wishbone Datasheet}\label{chap:wishbone}
Tbl.~\ref{tbl:wishbone}
\begin{table}[htbp]
\begin{center}
\begin{wishboneds}
Revision level of wishbone & WB B4 spec \\\hline
Type of interface & Slave, Read/Write \\\hline
Port size & 32--bit \\\hline
Port granularity & 32--bit \\\hline
Maximum Operand Size & 32--bit \\\hline
Data transfer ordering & (Irrelevant) \\\hline
Clock constraints & See the Datasheet for your part\\\hline
Signal Names & \begin{tabular}{ll}
		Signal Name & Wishbone Equivalent \\\hline
		{\tt i\_clk} & {\tt CLK\_I} \\
		{\tt i\_wb\_cyc} & {\tt CYC\_I} \\
		{\tt i\_wb\_stb} & {\tt STB\_I} \\
		{\tt i\_wb\_we} & {\tt WE\_I} \\
		{\tt i\_wb\_addr} & {\tt ADR\_I} \\
		{\tt i\_wb\_data} & {\tt DAT\_I} \\
		{\tt o\_wb\_ack} & {\tt ACK\_O} \\
		{\tt o\_wb\_stall} & {\tt STALL\_O} \\
		{\tt o\_wb\_data} & {\tt DAT\_O}
		\end{tabular}\\\hline
\end{wishboneds}
\caption{Wishbone Datasheet}\label{tbl:wishbone}
\end{center}\end{table}
is required by the wishbone specification, and so 
it is included here.  The big thing to notice is that this ICAPE2 interface
acts as a wishbone slave, and that all accesses to the ICAPE2 registers become
32--bit reads and writes to this interface.  Bit ordering is the normal
ordering where bit~31 is the most significant bit and so forth.  (Bit reversal
is accomplished internally to match Xilinx's definition.)  The {\tt o\_stall}
and {\tt o\_ack} lines are necessarily used to deal with the fact that
operations to the device take many clocks to complete (14 for writes, 21 for
reads), so be prepared to wait a couple of clocks for your access to complete.
Further, the {\tt o\_ack} line will go high while the bus is stalled in many
cases, indicating that the operation is complete but that the core is not
yet ready to handle a subsequent request.
 
\chapter{I/O Ports}\label{chap:ioports}
This core offers no I/O ports beyond those of the wishbone discussed in 
Chapt.~\ref{chap:wishbone}.  The I/O ports associated with the ICAPE2 interface
are captured internally, and not brought to the output of this core.
 
% Appendices
% Index
\end{document}