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}