Subversion Repositories sdspi

\documentclass{gqtekspec}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%

%% Filename:    spec.tex

%%

%% Project:     SD-Card controller, using a shared SPI interface

%%

%% Purpose:     This LaTeX file contains all of the documentation/description

%%              currently provided with the SDSPI controller core.  For those

%%      looking into here, this document is not nearly as interesting as the

%%      spec.pdf file it creates, so I'd strongly recommend reading that before

%%      diving into this document.  However, if you are interested in producing

%%      documents looking like this one, or using LaTeX in a similar fashion,

%%      you may find this document of use.

%%

%%      You should be able to find the PDF this file produces in the SVN

%%      distribution together with this LaTeX file and a copy of the GPL-3.0

%%      license this file is distributed under.  If not, just type 'make' in

%%      the doc directory (one up from this one), and it (should) build both

%%      pdf's without a problem.

%%

%% Creator:     Dan Gisselquist, Ph.D.

%%              Gisselquist Technology, LLC

%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%

%% Copyright (C) 2016, 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

%%

%%

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%%

%%

\usepackage{import}

\usepackage{bytefield}

\project{SDSPI Controller}

\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 \texttt{http://www.gnu.org/licenses/} for a copy.

\end{license}

\begin{revisionhistory}

0.1 & 6/18/2016 & Gisselquist & First Draft \\\hline

\end{revisionhistory}

% Revision History

% Table of Contents, named Contents

\tableofcontents

\listoffigures

\listoftables

\begin{preface}

When I started this project, I was informed that other projects similar to this

one existed.  The OpenRISC project has used an SD--Card controller, for example,

as has the Google project vault.  Of these two, the first uses the full SD--Card

interface which is unavailable on the XuLA2 board, and I could never find the

code for the second.

Still, had I found such interfaces, I would've still had another reason for

building my own: controlling the license.  By rolling my own interface, I can

offer it to anyone interested in it under the GPL license, such as you have

here.  Further, by not using code belonging to others, I am not restricted or

encumbered by any of their licenses--whether it be the GPL or otherwise.  This

code, and specification document, are therefore completely the product of

Gisselquist Technology, LLC.

That said, I am indebted to Mr.~Tambe for sharing his interface.  While the

current work does not use his approach and represents a complete rewrite, his

approach was valuable in helping me understand what the SD--Card specification

meant at several points along the way.

\end{preface}

\chapter{Introduction}

\pagenumbering{arabic}

\setcounter{page}{1}

% What is old

This Verilog core exports an SD card controller interface from internal to an

FPGA to the rest of the FPGA core, while taking care of the lower level details

internal to the interface.

% What does the old lack?

Unlike the other OpenCores SD Card controller\footnote{See

\texttt{http://www.opencores.org/project,sdcard\_mass\_storage\_controller}.}

which offers a full SD--interface, this controller focuses on the SPI interface

of the SD Card.  While this is a slower interface, the SPI interface is

necessary to access the card when using a XuLA2

board\footnote{See \texttt{http://www.xess.com/shop/product/xula2-lx25/}}, or

in general any time the full 9--bit, bi--directional interface to the SD card

has not been implemented.

Further, for those who are die--hard Verilog authors, this core is written in

Verilog as opposed to the XESS provided demonstration SD Card controller

found on GitHub\footnote{See

\texttt{https://github.com/xesscorp/VHDL\_Lib/SDCard.vhd}}, which was written

in VHDL.  For those who are not such die--hard Verilog authors, this controller

provides a lower level interface to the card than these other controllers.

Whereas the XESS controller will automatically start up the card and interact

with it, this controller requires external software to be used when interacting

with the card.  This makes the SDSPI controller both more versatile, in the

face of potential changes to the card interface, but also less--turn key.

% What is new

% What does the new have that the old lacks

% What performance gain can be expected?

While this core was written for the purpose of being used with the ZipCPU,

as enhanced by the Wishbone DMA controller used by the ZipCPU, nothing in this

core prevents it from being used with any other architecture that supports

the 32--bit Wishbone interface of this core.

This core has been written as a wishbone slave, not a master.  Using the core

together with a separate master, such as a CPU or a DMA controller, only makes

sense.  This design, however, also restricts the core from being able to use

the multiple block write or multiple block read commands, restricting us to

single block read and write commands alone.

\chapter{Architecture}\label{ch:arch}

This SD Card interface is designed to provide a means of commanding an SD Card,

via the SPI port, and returning its results.

The first thing to know about the SDSPI interface is that it is designed to work

over a shared SPI port.  Hence, when the SDSPI controller lowers the CS line to

select the SD--Card, the lowered line is only a request to an external

controller.  Once that external controller grants access to the SPI port to this

device, it will tell this controller and processing can continue.  If your

application does not have any contention for the SPI interface, you may simply

wire this grant line high.  The controller will still work, although it will

wait one clock more than necessary in that case before starting any transaction.

Second, the SDSPI core is completely controlled via the wishbone bus.  In

particular a command register is used to initiate interaction across the bus.

A separate data register is used to provide an argument to the command, and

two FIFO registers are used when transferring larger amounts of data to the

card.  We'll examine each of these interactions in turn.

Writes to the command register (CMD) will initiate actions across the port,

whether they be reads from or writes to the card.  These writes take the

form of sending a 48--bit command to the card.  The command sent to the card

is taken from the lower 8--bits of the command register, and the argument to the

command is taken from the DATA register.  The last 8--bits of the command sent

to the card are formed from a command CRC byte which the core generates

internally.  From the perspective of the Wishbone bus, writes to the register

will complete immediately, even though the action they initiate will may take

much longer to complete.  Further, writes made to the CMD register will be

silently ignored if the device is already busy.

Reads from the CMD register will always return immediately.  In particular, the

{\tt busy} bit, as returned by the CMD register, can be used to determine if the

interface is busy.

There is one exception to the rule that writes take many clocks to complete,

and that is writes which configure the SDSPI port.  Internal to the SDSPI

port is a configuration register, which determines the speed of the port

clock as well as the length of the FIFO (up to 128~samples, or 512--bytes).

To read the current speed and FIFO configuration, write an {\tt 0x00bf} value to

the command register.  This will cause the DATA register to be filled with

the internal configuration register.  Likewise writing a {\tt 0x0ff} to the

CMD register will cause the current DATA value, or specifically those non-zero

parts, to be transferred to the internal configuration register possibly setting

the clock divider and/or the FIFO length.

As part of each write to the CMD register, the controller must also be told

which type of response to expect from the SDSPI card.  Responses can be either

R1 (single byte), R1b (single byte, followed by a variable delay), or R1

followed by up to four bytes, such as the R2, R3, or R7 responses.

(Expected responses for particular commands may be found in the SD

Specifications documents.\footnote{This particular interface, and the examples

using it, were built using the SD Specifications, Part 1: Physical Layer

Simplified Specification, Version 4.10, dated 22 January, 2013.}

Finally, individual commands may or may not use the FIFO.  Commands that need

use of the FIFO will be specified by the {\tt use\_fifo} bit of the CMD

register.  Commands writing to the device will also set the {\tt fifo\_wr} bit

of the CMD register, whereas commands simply reading from the fifo will set the

{\tt use\_fifo} bit alone.

The DATA register is used during these transactions to first provide the

argument to the CMD interaction, and second to provide a place to put the

R2, R3, or R7 response after the transaction has completed.  The register will

be set to {\tt 0xffffffff} if not set by the response.

Finally, this core supports two separate FIFO's.  This allows a program to

fill (or read) one FIFO while the second FIFO can be read/written from the

SD card.  The FIFO internal address will be cleared and reset to the beginning

upon any write to the CMD register.  After clearing, the FIFO may be written

(read) one value at a time.  Reading both FIFO's in any interleaved fashion,

however, is not allowed as they share a common internal address.

Currently, the core will detect two types of errors in the interface.  The

first is a CRC error, and the second a timeout error.  Either error will set

an error bit in the CMD register.  Once set, only writing the error bit back

to the CMD register will clear it.

Now, if this discussion isn't thoroughly confusing, let's move on to the

Operation chapter to see some examples of how this might be used.

\chapter{Operation}\label{ch:ops}

This chapter will walk through some constants that can be used to simplify

interaction with the controller, the logic necessary to start up the card,

to read its registers, and then examples of how to read and write sectors

from the SD Card using this interface.

\section{Constants}

Since so much of the interface is controlled by the CMD register, it helps to

define several constants which can be used when issuing commands to the SD

Card.  Lets discuss some of these constants.

First, as discussed in the last chapter, the SDSPI core maintains an auxiliary

register to handle FIFO length and clock speed.  To set this register, we

define {\tt SD\_SETAUX} to {\tt 0x0ff}.  Thus, when {\tt SD\_SETAUX} is written

to the CMD register, the value of the DATA register is transferred to the

internal configuration.  Likewise, we also define {\tt SD\_READAUX} to

{\tt 0x0bf}.  When this value is written to the SD--Card, the internal

configuration registers value will be copied to the DATA regiseter.

\begin{tabular}{lll}

{\tt \#define} & {\tt SD\_SETAUX} & {\tt 0x0ff} \\

{\tt \#define} & {\tt SD\_READAUX}  & {\tt 0x0bf}

\end{tabular}

Second, every command to the SD--Card starts with a single byte.  Of that byte,

bit-7 must be clear and bit 6 set.  For this purpose, we define {\tt SD\_CMD}

to be {\tt 0x040}.  Thus, {\tt SD\_CMD+0} can be used to send an SD command

{\tt CMD0}, and {\tt SD\_CMD+1} can be used to send an SD command {\tt CMD1}.

\begin{tabular}{lll}

{\tt \#define} & {\tt SD\_CMD} & {\tt 0x040}

\end{tabular}

Third, for those commands that will read an SD--Card register, such as those

expecting an R2, R3, or R7 response from the card, we define {\tt SD\_READREG}

to be {\tt 0x0200}.  Thus, we can send a CMD8 by writing

\hbox{\tt SD\_CMD|SD\_READREG} to the port.

\begin{tabular}{lll}

{\tt \#define} & {\tt SD\_READREG} & {\tt 0x0200}

\end{tabular}

The next thing we'll want to be able to do is use the FIFO.  There are two

types of commands that use the FIFO, those that read from the card and those

that write to the card.  Both need the FIFO bit set, so we'll set

{\tt SD\_FIFO\_OP} to {\tt 0x0800} to be a read operation from the card, and

the same but with the write bit set {\tt SD\_WRITEOP} will be set to

{\tt 0x0c00} to write to the card.

\begin{tabular}{lll}

{\tt \#define} & {\tt SD\_FIFO\_OP} & {\tt 0x800} \\

{\tt \#define} & {\tt SD\_WRITEOP}  & {\tt 0xc00}

\end{tabular}

Finally, we want to be able to choose which FIFO we are using.  For this

purpose, we define {\tt SD\_ALTFIFO} to be {\tt 0x01000}.  When this bitmask

is included in a command, FIFO number one will be used for the command data,

otherwise FIFO zero.  (Note that this is separate from the DATA register,

which is still used for any command argument.)

\begin{tabular}{lll}

{\tt \#define} & {\tt SD\_ALTFIFO} & {\tt 0x1000}

\end{tabular}

Two other constants are necessary: {\tt SD\_BUSY}, set to {\tt 0x04000}, which

can be used to test when the SD interface is still busy, and {\tt SD\_ERROR},

set to {\tt 0x08000} which can be used to tell if an error has occurred.

Clearing an error may be done by writing {\tt SD\_ERROR} back to the card, but

to make things simpler we also create {\tt SD\_CLEARERR} for the same purpose.

\begin{tabular}{lll}

{\tt \#define} & {\tt SD\_BUSY} & {\tt 0x4000} \\

{\tt \#define} & {\tt SD\_ERROR} & {\tt 0x8000} \\

{\tt \#define} & {\tt SD\_CLEARERR} & {\tt 0x8000}

\end{tabular}

The two most important commands, though, are probably going to be those that

read and write a sector.  For these, we shall define {\tt SD\_READ\_SECTOR}

and {\tt SD\_WRITE\_SECTOR}.  As the first is a CMD17 to the card and the second

a CMD24, these can be defined as:

\begin{tabular}{lll}

{\tt \#define} & {\tt SD\_READ\_SECTOR} & {\tt ((SD\_CMD|SD\_CLEARERR|SD\_FIFO\_OP)+17)} \\

{\tt \#define} & {\tt SD\_WRITE\_SECTOR} & {\tt ((SD\_CMD|SD\_CLEARERR|SD\_WRITEOP)+24)}

\end{tabular}

`Or'ing the {\tt SD\_ALTFIFO} mask to either of these commands will cause the

interface to read from or write to the alternate FIFO.

As a very last \#define, we can define the macro {\tt SD\_WAIT\_WHILE\_BUSY}

to wait until the SD operation completes:

\begin{tabular}{lll}

{\tt \#define} & {\tt SD\_WAIT\_WHILE\_BUSY}&{\tt while(CMD \& SD\_BUSY)}

\end{tabular}

Alternatively, we could wait for an interrupt instead since the SDSPI core

will create an interrupt upon completion.  For now, and for this example,

we'll ignore interrupts.

\section{SD--Card Setup}

Setting up an SD--Card takes a bit of work.  There's a series of commands

and interactions that need to take place with the card before the card can

be used.  You can read about how to do this within the SD--Specification, so

we won't repeat the how's or why's here.  Instead, let's focus for now on

how this interaction can be made to take place using this controller.

The first step in any start up sequence is to clear the card from any

prior condition.  Hence we wait for the card to be no longer busy (it

shouldn't be busy anyway), and we then clear any errors:

\begin{tabbing}

{\tt SD\_WAIT\_WHILE\_BUSY;} \\

{\tt CMD} \= {\tt SD\_CLEARERR};

\end{tabbing}

Now that the controller is idle (which it should've been from startup anyway),

we can now set up our interface.  For this, we'll set our clock rate to 400~KHz.

The clock division register, sometimes erroneously called the speed, is found

in the lower eight bits of the soft-core configuration register.  The actual

SPI clock frequency, given this value, will be:

\begin{eqnarray}

f_{\mbox{\tiny SDSPI}} &=& \frac{f_{\mbox{\tiny CLK}}}{2\left(\mbox{\tt CLKDIV}+1\right)}

\end{eqnarray}

Hence, since the XuLA2-LX25 SoC runs at an 80~MHz clock, setting this value to

{\tt 0x63} sets the SPI clock to 400~kHz.

\begin{tabbing}

{\tt DATA} \= {\tt = 0x063}; \\

{\tt CMD} \> {\tt = SD\_SETAUX};

\end{tabbing}

Note that we could have also set the higher order configuration bits to set

the size of the FIFO.  In particular, the next four bits, bits 8--11, set

the FIFO length.  Setting these to zero will cause the controller to ignore

the change, whereas setting the value to three will set the FIFO length to

$4\cdot2^3$ bytes, and setting it to seven will set the FIFO length to the

nominal $4\cdot 2^7$ or $512$~bytes.

The controller is now ready to send commands to the SD card.  The first command

to the card is always a command zero, with zero data.  This is sometimes

called the \hbox{\tt GO\_IDLE\_STATE} command.  We then wait for the

command to complete:

\begin{tabbing}

{\tt DATA} \= {\tt = 0;} \\

{\tt CMD} \> {\tt = SD\_CMD+0;} \\

{\tt SD\_WAIT\_WHILE\_BUSY;}

\end{tabbing}

The card should now be in its idle state.

The next part of the negotiation tells the card whether or not we are able to

handle high capacity cards.  For this, we send a command one,

\hbox{\tt SEND\_OP\_COND}, with an argument of {\tt 0x40000000} to tell it

that we are able to support high capacity cards.  (An argument of zero would

mean that we could not.)

\begin{tabbing}

{\tt DATA} \= {\tt = 0x40000000;} \\

{\tt CMD} \> {\tt = SD\_CMD+1;} \\

{\tt SD\_WAIT\_WHILE\_BUSY;}

\end{tabbing}

Then the card needs to know what voltage it will be run at.  We communicate this

via a \hbox{\tt SEND\_IF\_COND} command, or CMD8.  Since the XuLA2

only operates the card at 3.3V, we tell the card we wish to run at 3.3V in the

argument.  The last eight bits of the argument, however, are simply to determine

whether communication has taken place.  We set these bits to {\tt 0x0a5},

although they could be anything.  The card will echo this value back in the

response:

\begin{tabbing}

{\tt DATA} \= {\tt = 0x1a5;} \\

{\tt CMD} \> {\tt = SD\_CMD+8;} \\

{\tt SD\_WAIT\_WHILE\_BUSY;} \\

{\em // assert((DATA\&0x0ff)==0x01a5);}

\end{tabbing}

The card will also echo back the voltage range, if it accepts it.  Thus,

we should receive {\tt 0x01a5} as a response.

The card will now try to start up its own internal state machines.  This could

take a while.  We therefore poll the device, and wait for its startup sequence

to complete:

\begin{tabbing}

{\tt bool dev\_busy = false;} \\

{\tt do \{}\=\\

\> {\em // CMD55 gives us access to SD specific commands}\\

\> {\tt DATA = 0;}\\

\> {\tt CMD = SD\_CMD+55;}\\

\> {\tt SD\_WAIT\_WHILE\_BUSY;}\\

\\

\> {\em // Now we can issue the ACMD41, to get the idle}\\

\> {\em // status}\\

\> {\tt DATA = 0x40000000;} \\

\> {\tt CMD = SD\_CMD+41;} \\

\> {\tt DATA} \= {\tt = 0x1a5;} \\

\> {\tt CMD} \> {\tt = SD\_CMD+8;} \\

\> {\tt SD\_WAIT\_WHILE\_BUSY;} \\

\\

\> {\em // The R1 response can be found in the lower 8 bits}\\

\> {\em // of the CMD register after the command is complete.}\\

\> {\em // Bit 1 of R1 indicates the card hasn't finished its}\\

\> {\em // startup}\\

\> {\tt dev\_busy = CMD\&1;}\\

{\tt \} while(dev\_busy);}

\end{tabbing}

\section{Reading Card Registers}

Once the card has started, we can request its operating conditions register,

or OCR register as it is called.  For this, we issue a {\tt READ\_OCR} command,

or CMD58 by number.  Since this command returns a 32--bit value, we use the

{\tt SD\_READREG} macro as well:

\begin{tabbing}

{\tt int OCR;}\\

\\

{\tt DATA} \= {\tt = 0;} \\

{\tt CMD} \> {\tt = (SD\_READREG|SD\_CMD)+58;} \\

{\tt SD\_WAIT\_WHILE\_BUSY;} \\

{\tt OCR} \= {\tt = DATA;}\\

\end{tabbing}

When I issue this command on my card, I get a {\tt 0xc0ff8000} response telling

me that my card can handle between 2.7 and 3.6~Volts, that it is a higher

capacity card, and that it has completed its startup sequence.

Now let's switch up to a higher speed, and read the 16--byte Card Specific

Data (CSD) register field from the card.  First, the switch to a 20~MHz clock

and a 16--byte fifo,

\begin{tabbing}

{\tt DATA} \= {\tt = 0x0201}; \\

{\tt CMD} \> {\tt = SD\_SETAUX};

\end{tabbing}

Remember that the {\tt 0x0200} switches to a FIFO of length~$2^2$ words, or

equivalently $4\cdot 2^2=16$ bytes.  Likewise the {\tt 0x01} component switches

our frequency to 20~MHz.  Now we can issue the {\tt SEND\_CSD\_COND}, or

CMD9, command itself.  Note that we didn't need to wait for the {\tt SD\_SETAUX}

command to complete.  Further, since this command is going to read from our

FIFO, we need to include the {\tt SD\_FIFO\_OP} part of the command:

\begin{tabbing}

{\tt int CSD[4];}\\

{\tt DATA} \= {\tt = 0;} \\

{\tt CMD} \> {\tt = (SD\_FIFO\_OP|SD\_CMD)+9;}

{\tt SD\_WAIT\_WHILE\_BUSY;} \\

{\tt for(int i=0; i<4; i++) } \\

\> {\tt CSD[i] = FIFO[0];}

\end{tabbing}

Once the command is complete, we can read the four 32--bit words of the CSD

register from the FIFO, as shown above.  Alternatively, we could have issued

another command first, before reading that FIFO result.

We could read the Card Identification (CID) register as well, but this would've

been the same sequence as above, save only that we would've written a

{\tt (SD\_READREG|SD\_CMD)+10)} to CMD.

Reading the STATUS is similar, only the response to the {\tt SEND\_STATUS}

command is an 8--bit value from an R2 response, not the 32--bit values of

the R3 (OCR) or R7 responses.  Still, the R2 response is provided in the

DATA register, so we only need to send {\tt (SD\_READREG|SD\_CMD)+13} to

the CMD register in order to read its result from the DATA register.  The status

register will be returned in the top eight bits of the DATA register (the

interface still reads 32--bits, even though the other 24 can be ignored), so:

\begin{tabbing}

{\tt int card\_status;}\\

{\tt DATA} \= {\tt = 0;} \\

{\tt CMD} \> {\tt = (SD\_READREG|SD\_CMD)+13;}

{\tt SD\_WAIT\_WHILE\_BUSY;} \\

{\tt card\_status = DATA>>24;}

\end{tabbing}

As a final register example, let's read the SD Card Configuration Register

(SCR).  This register is read in a fashion very similar to the CSD register,

except that because of its width the FIFO needs to be set for a shorter

register width:

\begin{tabbing}

{\tt int SCR[2];}\\

{\em // Set the FIFO length to two words, $2^1$.}\\

{\tt DATA} \= {\tt = 0x0100}; \\

{\tt CMD} \> {\tt = SD\_SETAUX};\\

{\em // Issue an ALT command, to get the other command set.}\\

{\tt DATA} \= {\tt = 0;} \\

{\tt CMD} \> {\tt = (SD\_CMD)+55;}\\

{\tt SD\_WAIT\_WHILE\_BUSY;} \\

{\em // Now get the SCR register.}\\

{\tt DATA} \= {\tt = 0;} \\

{\tt CMD} \> {\tt = (SD\_FIFO\_OP|SD\_CMD)+51;}\\

{\tt SD\_WAIT\_WHILE\_BUSY;} \\

{\tt for(int i=0; i<2; i++) } \\

\> {\tt SCR[i] = FIFO[0];}\\

\end{tabbing}

\section{Reading and Writing}

For our first example, let's read the boot sector from our card.  For this,

we set our FIFO back to 128~words (512~bytes), and then issue a read sector

command:

\begin{tabbing}

{\tt void} \= {\tt read(int sector\_num, int *buf) \{}\\

\> {\em // Set the FIFO length to 128 words, $2^7$.}\\

\> {\tt DATA} \= {\tt = 0x0700}; \\

\> {\tt CMD} \> {\tt = SD\_SETAUX};\\

\> {\em // Read from the requested sector}\\

\> {\tt DATA} \= {\tt = sector\_num;} \\

\> {\tt CMD} \> {\tt = SD\_READ\_SECTOR;}\\

\> {\tt SD\_WAIT\_WHILE\_BUSY;} \\

\> {\tt for(int i=0; i<128; i++) } \\

\> \> {\tt buf[i] = FIFO[0];}\\

{\tt \}}

\end{tabbing}

We could also write to any sector on the card in a very similar fashion:

\begin{tabbing}

{\tt void} \= {\tt write(int sector\_num, int *buf) \{}\\

\> {\em // Set the FIFO length to 128 words, $2^7$.}\\

\> {\tt DATA} \= {\tt = 0x0700}; \\

\> {\tt CMD} \> {\tt = SD\_SETAUX};\\

\> {\em // Fill the FIFO with our data}\\

\> {\tt for(int i=0; i<128; i++) } \\

\> \> {\tt FIFO[0] = buf[i];}\\

\> {\em // Issue the write command}\\

\> {\tt DATA} \= {\tt = sector\_num;} \\

\> {\tt CMD} \> {\tt = SD\_WRITE\_SECTOR;}\\

\> {\tt SD\_WAIT\_WHILE\_BUSY;} \\

{\tt \}}

\end{tabbing}

As mentioned in the introductory chapter, this interface does not support

reading or writing multiple blocks at once.  Hence, I expect all interaction

using this card controller to be accomplished through these two commands:

reading a single sector, and writing to a single sector.

\chapter{Registers}\label{ch:regs}

As mentioned in the last two chapters, the SDSPI core has only four registers,

and one internal register.  These are shown in Tbl.~\ref{tbl:ioregs}.

\begin{table}[htbp]

\begin{center}\begin{reglist}

CMD     &{\tt 0x00} & 32 & R/W & SDSPI Command register\\\hline

DAT     &{\tt 0x01} & 32 & R/W & SDSPI return data/argument register\\\hline

FIFO[0] &{\tt 0x02} & 32 & R/W & FIFO[0] data\\\hline

FIFO[1] &{\tt 0x03} & 32 & R/W & FIFO[1] data\\\hline

CONFIG  &  & 12 & R/W & Internal configuration register\\\hline

\end{reglist}

\caption{I/O Peripheral Registers}\label{tbl:ioregs}

\end{center}\end{table}

The most powerful of these is the command register, CMD, so we'll spend most of

our time discussing that one.

\section{CMD Register}

Writes to the CMD register will cause the device to act, or if the device is

already busy then any writes will be ignored.  The CMD register itself is

composed of several packed bit fields, as shown in Fig.~\ref{fig:CMD}.

\begin{figure}\begin{center}

\begin{bytefield}[endianness=big]{32}

\bitheader{0-31}\\

\bitbox{15}{Unused}

\bitbox{1}{C}

\bitbox{1}{E}

\bitbox{1}{B}

\bitbox{1}{0}

\bitbox{1}{I}

\bitbox{1}{F}

\bitbox{1}{W}

\bitbox{2}{R}

\bitbox{8}{R1/CMD}

\end{bytefield}

\caption{CMD Register fields}\label{fig:CMD}

\end{center}\end{figure}

Perhaps the most important of these is the R1/CMD field.  If bits 7--6 are

the two bits 2'b01, then the write is a command and the bottom six bits

specify the rest of the 8--bit command identifier.  Once the command is

complete, these 8--bits represent the R1 response from the device.  R1

should be one while the device is still starting, or zero in the case of no

error.  Further interpretation of this value may be found in the SD--Card

Specification.

Of next importance is the $R$ field.  This specifies the response the

controller should expect from the card given the command that was issued

to the card.  There are three possible values for this field: $2'b00$, meaning

the controller should expect an R1 response, $2'b01$, meaning the controller

should expect an R1b response, and $2'b10$ meaning the controller should

expect an R2/R3/R7 32--bit response.

The $F$, or FIFO, field should be set if the command being given requires the

use of the FIFO.  $W$ should be set at the same time if the controller will be

writing to the card from the FIFO, and cleared if the controller will be

reading from the card into the FIFO.  Finally, $I$ specifies which FIFO will

be used: 0 for the primary, or 1 for the alternate.

While the command is running, the BUSY or $B$ bit will be set.

Once the command has completed, the $E$ bit may be set if either the command

timed out, or a CRC error was noted while reading from the card.  (To detect

a CRC error when writing to the card, check the R1 response according to the

SD Card specification.)  Errors may be cleared by writing a 1 to this bit.

Until such time as an error is cleared, the error condition will simply

persist.

\section{DATA Register}

Compared to the CMD register, the DATA register is quite simple.  Like the

CMD register, the DATA register may only be written when the interface is

idle.  When issuing a command to the device, the 32--bit argument for the

command is taken from the DATA register.  When reading the results of a device

command, the DATA register will contain the R2 response in the upper 8--bits,

or an R3 or R7 response in the full 32--bits.

\section{FIFO Registers}

The SDSPI controller maintains two 128~word (512~byte) FIFOs.  Reads from the

card will read data into one of the two FIFO's, whereas writes to the card will

write data out from one of the FIFO's.  Which FIFO the card uses is determined

by the $I$ bit in the CMD register (above).

Further, upon any write to the CMD register, the FIFO address will be set

to point to the beginning of the FIFO.

The purpose of the FIFO's is to allow one to issue a command to read into one

FIFO, then when that command is complete to read into a second FIFO.  While

the second command is ongoing, a CPU or DMA may read the data out of the first

FIFO and place it wherever into memory.  Then, when the second read is complete,

a third read may be issued into the first buffer while the data is read out of

the second and so forth.

This interleaving approach, sometimes called ping-pong buffering, can also be

used for writing: Write into one FIFO, issue a write command, write into the

second FIFO, wait for the first write command to complete, issue a second

write command, and so forth.

One item to note before closing: there is only one internal address register

when accessing the FIFO from the wishbone bus.  Attempts to read from or write

to either FIFO from the wishbone bus will increment this address register.

Interleaved read, or write attempts, such as reading one item from

FIFO[0] and writing another item to FIFO[1], will each increment the internal

address pointer so that the result is likely to be undesirable.  For this

reason, it is recommended that only one FIFO be read from or written by the

wishbone bus at a time.

\section{CONFIG Register}

The CONFIG register controls the SPI clock rate and the FIFO size.

Specifically, with regards to the FIFO size, it controls how many bytes will

be written into the FIFO (which is really of a fixed size) before the expecting

a CRC, or equivalently how many bytes to read out of the FIFO before adding a

CRC.  The fields of this register are shown in Fig.~\ref{fig:CONFIG}.

\begin{figure}\begin{center}

\begin{bytefield}[endianness=big]{32}

\bitheader{0-31}\\

\bitbox{8}{Unused}

\bitbox{8}{Max LgFIFO}

\bitbox{8}{LgFIFO}

\bitbox{2}{0}

\bitbox{6}{CLKDIV}

\end{bytefield}

\caption{CONFIG Register fields}\label{fig:CONFIG}

\end{center}\end{figure}

The CLKDIV field sets a divisor from the current clock to create a SPI clock.

The minimum value of this field is `1', corresponding to dividing the input

clock by `4'.  As discussed earlier, the input clock will be divided by

twice this field plus one.  Hence, setting this field to one will cause the

original clock to be divided by $2(1+{\tt CLKDIV})$ or $4$.  Thus an 80~MHz

input clock will become a 20~MHz SPI clock.  Setting this value to zero will

cause the set to be ignored.

The LgFIFO field sets the log, base two, of the FIFO size.  The actual FIFO

size used will be $2^{\mbox{\tiny LGFIFO}}$ words.  The maximum size the

device will support is returned by the {\tt Max LgFIFO} field, which is

currently set to $7$ for a 128~word (512~byte) FIFO.

To set the CONFIG register, first set the DATA register to the new config

value (or zero for the fields that will not change), and then write

{\tt 0x0ff} to the CMD register.  Likewise, to read the CONFIG register

write a {\tt 0x0bf} to the CMD register and read the CONFIG register from the

DATA register.

\chapter{Wishbone Datasheet}\label{ch:wb}

Tbl.~\ref{tbl:wishbone}

\begin{table}[htbp]

\begin{center}

\begin{wishboneds}

Revision level of wishbone & WB B4 spec \\\hline

Type of interface & Slave, (Block/pipelined) Read/Write \\\hline

Port size & 32--bit \\\hline

Port granularity & 32--bit \\\hline

Maximum Operand Size & 32--bit \\\hline

Data transfer ordering & Big Endian \\\hline

Clock constraints & (See below)\\\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 Slave Datasheet}\label{tbl:wishbone}

\end{center}\end{table}

is required by the wishbone specification, and so it is included here.  Note

that all wishbone operations may be pipelined, to include FIFO operations,

for speed.

The particular constraint on the clock is not really a wishbone constraint, but

rather an SD--Card constraint.  Not all cards can handle clocks faster than

25~MHz.  For this reason, the wishbone clock, which forms the master clock for

this entire controller, must be divided down so that the SPI clock is within

the limits the card can handle.

\chapter{Clocks}\label{ch:clk}

This core is based upon the XuLA2-LX25 SoC design.  The XuLA2 development board

contains one external 12~MHz clock, which is internally boosted within the SoC

to 80~MHz.  This clock is divided by a programmable divider, often set to

four, to create the 20~MHz clock used to drive the device.  (Maximum device

speed is usually 25MHz, although some devices can run at 50~MHz.)   This

controller does not support setting the SPI clock frequency any faster than

one quarter of the input clock rate.

\chapter{I/O Ports}\label{ch:io}

Table.~\ref{tbl:ioports}

\begin{table}[htbp]

\begin{center}

\begin{portlist}

i\_clk & 1 & Input & Clock\\\hline\hline

i\_wb\_cyc & 1 & Output & Wishbone bus cycle active\\\hline

i\_wb\_stb & 1 & Output & Wishbone Strobe, true one clock only for each interaction\\\hline

i\_wb\_we & 1 & Output & Wishbone Write-Enable line\\\hline

i\_wb\_addr & 2 & Output & Selects our I/O register\\\hline

i\_wb\_data & 32 & Output & Incoming wishbone bus data\\\hline

o\_wb\_ack & 1 & Output & Acknowledge a WB request, always true one clock after the request\\\hline

o\_wb\_stall & 1 & Output & Always zero\\\hline

o\_wb\_data & 32 & Output & 32--bit wishbone data response\\\hline\hline

o\_cs\_n & 1 & Output & Chip--select and SPI request line\\\hline

o\_sck & 1 & Output & SD Card clock\\\hline

o\_mosi & 1 & Output & Output data wire to the SD Card\\\hline

i\_miso & 1 & Input & Input data wire from the SD Card\\\hline\hline

o\_int & 1 & Output & An interrupt line to the CPU controller\\\hline

i\_bus\_grant & 1 & Input  & True if the SDSPI controller is controlling the bus\\\hline

o\_debug & 32 & Output & See Verilog for details\\\hline

\end{portlist}

\caption{List of IO ports}\label{tbl:ioports}

\end{center}\end{table}

lists all of the input and output ports to this core.  You may notice these

inputs and outputs are divided into sections: the master clock, the wishbone

bus, the SPI interface to the card, and three other wires.  Of these, the

last two chapters discussed the wishbone bus interface and the clock.  The

SPI interface should be fairly straightforward, so we'll move on and discuss

the other three wires.

This controller supports an interrupt line, {\tt o\_int}.  Upon completion of

any operation, when the SPI chip select line is deactivated (raised high),

{\tt o\_int} will be strobed for one cycle.  It is up to the logic using this

chip to catch and use that interrupt line or ignore it.  In particular, it is

possible to use that interrupt line to trigger a DMA service to move data

in or out of the FIFO, although the details of that are beyond this discussion

here.

The second wire, {\tt i\_bus\_grant}, exists because this controller is

expected to operate together with other SPI controllers that may also wish

to drive the same three wires ({\tt o\_sck} and {\tt o\_mosi} to the device,

and {\tt i\_miso} from the device).  When the controller therefore lowers the

{\tt o\_cs\_n} line to make it active, it then waits for {\tt i\_bus\_grant}

to go high.  This is its signal, from the outside world, that its chip has been

selected and that it is now driving the {\tt o\_sck} and {\tt o\_mosi} pins.

Should you not need this in your environment, you can simply leave this line

wired high.

The final bus of 32--wires, {\tt o\_debug}, is defined internally and used

when/if necessary to debug the core and watch what is going on within it.

These wires may be left unconnected in most implementations, as they are not

necessary for using the actually controller.

% Appendices

% Index

\end{document}