Subversion Repositories wbscope

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%% Filename: 	spec.tex
%%
%% Project:	Wishbone scope
%%
%% Purpose:	This LaTeX file contains all of the documentation/description
%%		currently provided with this Wishbone scope 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{Wishbone Scope}
\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.1 & 6/22/2015 & Gisselquist & First Draft \\\hline
\end{revisionhistory}
% Revision History
% Table of Contents, named Contents
\tableofcontents
% \listoffigures
\listoftables
\begin{preface}
 
This, then, was and is the genesis of this project.
\end{preface}
 
\chapter{Introduction}
\pagenumbering{arabic}
\setcounter{page}{1}
 
The wishbone Scope is a debugging tool for reading results from the chip after
events have taken place.  In general, the scope records data until some
trigger has taken place, and then continues for some user programmable hold off.
Once the holdoff has been reached, the scope stops recording and asserts an
interrupt.  At this time, data may be read from the scope in order from oldest
to most recent.  That's the basics, now for two extra details.
 
First, the trigger and data that the scope records is implementation dependent.
The scope itself is designed to be easily reconfigurable from one build to the
next so that the actual configuration may even be build dependent.
 
Second, the scope is built to be able to run off of a separate clock from the
bus that commands and controls it.  This is configurable, set the parameter
``SYNCHRONOUS'' to `1' to run off of a single clock.  When running off  of two
clocks, it means that actions associated with commands issued to the scope, such
as manual triggering or being disabled or released, will not act synchronously
with the scope itself.
 
Third, the data clock associated with the scope has a clock enable line
associated with it.  Depending on how often the clock enable line is enabled
may determine how fast the scope is primed, triggered, and eventually completes
its collection.
 
% \chapter{Architecture}
\chapter{Operation}
 
So how shall one use the scope?  First, before using the scope, the holdoff
needs to be set.  The scope is designed so that setting the scope control value
to the holdoff alone will reset the scope from whatever condition it was in,
freeing it to run.  Once running, then upon every clock enabled clock, one
sample of data is read into the scope and recorded.  Once every memory value
is filled, the scope has been {\tt PRIMED}.  Once the scope has been
{\tt PRIMED}, it will then be responsive to its trigger.  Should the trigger be
active on a clock--enabled input, the scope will then be {\tt TRIGGERED}.  It
will then count for the number of clocks in the holdoff before stopping collection, placing it in the {\tt STOPPED} state.  If the holdoff is zero, the last
sample in the buffer will be the sample containing the trigger.
 
There are two further commands that will affect the operation of the scope.  The
first is the {\tt MANUAL} trigger command/bit.  This will cause the scope to
trigger immediately if set.  If coupled with a {\tt RESET} command, the trigger
will first wait until it is {\tt PRIMED} before the manual trigger takes
effect. 
 
The last command that can affect the operation of the scope is the {\tt DISABLE}
command/bit.  This command will prevent the scope from triggering, or if 
triggered, prevent the scope from generating an interrupt.
 
\chapter{Registers}
 
This scope core supports two registers, as listed in
Tbl.~\ref{tbl:reglist}.  The first is the control register, whereas the second
is the data register.
\begin{table}[htbp]
\begin{center}
\begin{reglist}
WBSCOPE		& 0 & 32 & R/W & Configuration, control, and status of the
		scope.\\\hline
WBSCOPEDATA	& 1 & 32 & R & Read out register, to read out the data
		from the core.\\\hline
\end{reglist}\caption{List of Registers}\label{tbl:reglist}
\end{center}\end{table}
Each register will be discussed in detail in this chapter.
 
\section{Control Register}
The bits in the control register are defined in Tbl.~\ref{tbl:control}.
\begin{table}[htbp]
\begin{center}
\begin{bitlist}
31 & R/W & RESET\_n.  Write a `0' to this register to command a reset.
	Reading a `1' from this register means the reset has not finished
	crossing clock domains and is still pending.\\\hline
30 & R & STOPPED, indicates that all collection has stopped.\\\hline
29 & R & TRIGGERRED, indicates that a trigger has been recognized, and that
	the scope is counting for holdoff samples before stopping.\\\hline
28 & R & PRIMED, indicates that the memory has been filled, and that the
	scope is now waiting on a trigger.\\\hline
27 & R/W & MANUAL, set to invoke a manual trigger.\\\hline
26 & R/W & DISABLE, set to disable the internal trigger.  The scope may still
	be triggered manually.\\\hline
25 & R & RZERO, this will be true whenever the scope's internal address
	register is pointed at the beginning of the memory.\\\hline
20--24 & R & LGMEMLEN, the base two logarithm of the memory length.  Thus,
	the memory internal to the scope is given by 1<<LGMEMLEN. \\\hline
0--19 & R/W & Unsigned holdoff\\\hline
\end{bitlist}
\caption{Control Register}\label{tbl:control}
\end{center}\end{table}
 
\section{Data Register}
 
This is perhaps the simplest register to explain.  Before the core stops
recording, reads from this register will produce reads of the bits going into
the core, save only that they have not been protected from any meta-stability
issues.  This is useful for reading what's going on when the various lines are
stuck.  After the core stops recording, reads from this register return values
from the stored memory.  Further, after recording has stopped, every read
increments an internal memory address, so that after $N$ reads (for however
long the internal memory is), the entire memory has been returned over the bus.
If you would like some assurance that you are reading from the beginning of the
memory, check the control register's {\tt RZERO} flag.
 
\chapter{Clocks}
 
This scope supports two clocks: a wishbone bus clock, and a data clock.
If the internal parameter ``SYNCHRONOUS'' is set to zero, proper transfers
will take place between these two clocks.  Setting this parameter to a one
will save some flip flops and logic in implementation.
 
\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, pipeline reads supported \\\hline
Port size & 32--bit \\\hline
Port granularity & 32--bit \\\hline
Maximum Operand Size & 32--bit \\\hline
Data transfer ordering & (Irrelevant) \\\hline
Clock constraints & None.\\\hline
Signal Names & \begin{tabular}{ll}
		Signal Name & Wishbone Equivalent \\\hline
		{\tt i\_wb\_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 core
acts as a wishbone slave, and that all accesses to the wishbone scope
registers become 32--bit reads and writes to this interface. 
 
\chapter{IO Ports}
 
The ports are listed in Table.~\ref{tbl:ioports}.
\begin{table}[htbp]
\begin{center}
\begin{portlist}
i\_clk & 1 & Input & \\\hline
i\_ce & 1 & Input & Clock Enable.  Set this high to clock data in and
		out.\\\hline
i\_trigger & 1 & Input &
		\\\hline
i\_data & 32 & Input &
		\\\hline
i\_wb\_clk & 1 & Input & The clock that the wishbone interface runs on.
		\\\hline
i\_wb\_cyc & 1 & Input & Indicates a wishbone bus cycle is active when high.
		\\\hline
i\_wb\_stb & 1 & Input & Indicates a wishbone bus cycle for this peripheral
		when high.  \\\hline
i\_wb\_we & 1 & Input & Write enable, allows configuring the part.
		\\\hline
i\_wb\_addr & 1 & Input & A single address line, set to zero to access the
		configuration and control regiseter, to one to access the data
		register.  \\\hline
i\_wb\_data & 32 & Input & Data used when writing to the control register,
		ignored otherwise.  \\\hline
o\_wb\_ack & 1 & Output & Wishbone acknowledgement.  This line will go high
		on the clock after any wishbone access, as long as the wishbone
		{\tt i\_wb\_cyc} line remains high (i.e., no ack's if you 
		terminate the cycle early).
		\\\hline
o\_wb\_stall & 1 & Output & Required by the wishbone spec, but always set to
		zero in this implementation.
		\\\hline
o\_wb\_data & 32 & Output & Values read, either control or data, headed back
		to the wishbone bus.
		\\\hline
\end{portlist}
\caption{List of IO ports}\label{tbl:ioports}
\end{center}\end{table}
% Appendices
% Index
\end{document}