Subversion Repositories openarty

\usepackage{listings}

0.0 & 11/18/2016 & Gisselquist & Added a getting started section\\\hline

At {\$ 99}, the Arty is a very economical FPGA platform for doing

a lot of things.  It was designed to support the MicroBlaze soft CPU platform,

and as a result it has a lot more memory plus ethernet support.  Put together,

it feels like it was designed for soft--core CPU development.  Indeed, it has

an amazing capability for its price.

Instructions and examples for using the Arty, however, tend to focus on

schematic design development techniques.  While these may seem like an

appropriate way to introduce a beginner to hardware design, these techniques

introduce a whole host of problems.

The first and perhaps biggest problem is that it can be difficult to trouble

shoot what is going on.  This is a combination of two factors.  The first is

that many of the reference schematic designs make use of proprietary IP.  In

an effort to protect both their IP and themselves, companies providing such

IP resources often make them opaque, and difficult to see the internals of.

As a result, it can be difficult to understand why that IP isn't working in

your design.  Further, while many simulation tools exist, only the Xilinx tools

will allow full simulation of Xilinx proprietary IP.  Finally, while it may be

simple to select a part and ``wire'' it up within a schematic, most IP

components have many, many configuration options which are then hidden from the

user within the simplified component.  These options may be the difference

between successfully using the component and an exercise in frustration.

Put together, all of these features of schematic design make the design more

difficult to troubleshoot, and often even impossible to troubleshoot using

open source tools such as Verilator.

Another problem is that schematic based designs often hide their FPGA resource

usage.  They can easily become resource hogs, leaving the designer unaware

of the consequences of what he/she is implementing.  As an example, the memory

interface generated by Xilinx's Memory Interface Generator (MIG) consumes

nearly a full quarter of the Arty's FPGA resources, while delaying responses

to requests by upwards of 250~ns.  Further, while Xilinx touts its MicroBlaze

processor as only using 800--2500 LUTs, the MicroBlaze architecture requires

it be connected to four separate AXI busses, with each of those having

five channels, all with their requests and acknowledgement flags.  These

can therefore easily consume all of the resources within an architecture, before

providing any of the benefit the designer was looking for when they chose to

use an FPGA.

First, the OpenArty is entirely built in Verilog, and (with the exception of

the MIG controller), it is entirely buit out of OpenSource IP.\footnote{I'm

still hoping to place an open memory controller into this design.  This

controller is written in logic, but does not yet connect to any hardware ports.}

Second, configuration options, such as cache sizes, can be fine tuned via a

CPU options file.

Third, as you will find from examining the RTL sources, this project uses only

one bus, and that bus has ony one channel associated with it: a Wishbone Bus.

This helps to limit the logic associated with trying to read and write from

the CPU, although it may increase problems with fanout.

Finally, because the OpenArty project is made from open source components, the

entire design, together with several of its peripherals, can be simulated using

Verilator.  This makes it possible to run programs on the ZipCPU within the

OpenArty design, and find and examine where such programs (or their peripherals)

fail.

Overall, the goals of this OpenArty project include:

\item Use all of Arty's on--board hardware: Flash, DDR3-SDRAM, Ethernet, and

        everything else at their full and fastest speed(s).  For example, the

        flash will need to be clocked at 82~MHz, not the 50~MHz I've clocked

        it at in previous projects.  The DDR3 SDRAM memory should also be able

        to support pipelined 32--bit interactions over the Wishbone bus at a

        162~MHz clock.  Finally, the Ethernet controller should be supported

        by a DMA capable interface that can drive the ethernet at its full

        100Mbps rate.

        (Of these, only the ethernet goal has been met.)

\item Run using a 162.5~MHz system clock, if for no other reason than to gain

        the experience of building logic that can run that fast.\footnote{The

        While the wishbone bus has been upgraded so that it may run at

        200~MHz, the CPU and memory controller cannot handle this speed (yet).

\item The default configuration will also include four Pmods: a USBUART,

        a GPS, an SDCard, and an OLEDrgb.

        (These have all been tested, and are known to work.)

        While the GPS tracking circuit is in place, and while it appears to be

        able to track a GPS signal to within about 100ns or so, the

        network stack has yet to be built.

\item A ZipOS that can actually load and run programs from the SD Card, rather

        than just a static memory image stored in flash on start-up.

        At this point, the MMU has been written and has passed its bench

        testing phase.  It has not (yet) been integrated with the CPU.

\chapter{Getting Started}\label{ch:getting-started}

\section{Building the Core}

%

\section{Building the board support files}

The OpenArty project comes with a series of board support programs that are

designed to run from a Linux command line.  The C++ source code for these

programs can be found in the sw/host directory.  These programs have two

dependencies: the ZipCPU load program depends upon libelf, and the ZipCPU

debugger depends upon the ncurses library.  If you have these two libraries,

your build should proceed without problems.

% TODO: Remove the dependency on ZIPD.

A make in the sw/host directory should build all of these support programs.

These include:

\begin{itemize}

\item {\tt wbregs}: a program to read and write addresses on the wishbone bus,

        and hence to test peripherals independent of the CPU.

\item {\tt netuart}: a program to convert the UART device provided by the board

        to a TCP/IP device that can be connected to anywhere.

\item {\tt wbsettime}: a simple program to set the time on the real-time clock

        core within the board.

\item {\tt dumpflash}: reads the current contents from the flash memory into a

        local file

\item {\tt wbprogram}: programs new configuations into the flash

\item {\tt netsetup}: reads and decodes the MDIO interface from the ethernet

        PHY controller

\item {\tt manping}: pings a computer using the ethernet packet interface.

        This program does not have any ARP handling, so while it will wait

        for a reply, the reply typically comes back in the form of an ARP

        request rather than the ping response.

\item {\tt zipload}: Loads a program onto the ZipCPU, adjusting flash, block

        RAM, and or SDRAM memory to do so.  May also start the program running

        if requested.

\item {\tt zipstate}: Returns information about whether or not the CPU is

        running, is running in user mode, is waiting for an interrupt,

        has halted, etc.

\item {\tt zipdbg}: a debugger with the capability to halt, reset and step

        the CPU, as well as to inspect the state of the CPU following any

        unexpected halt.

\end{itemize}

\section{Initially installing the core}

The OpenArty core may be installed onto the board via the Xilinx Hardware

Manager.  If properly set up, you should be able to open the hardware

manager after you build an initial bit stream, open the Arty, select the

toplevel bit file, and request Xilinx to load the file.

If you are successful, the four color LEDs will blank while the hardware

manager is loading the hardware, and then turn to varying intensities of red.

\section{Connecting the PMods}

The OpenArty project is designed to work with four PMods: PModUSBUART,

PModGPS, PModSD, and PModOLEDrgb.  These four provide the device with

serial port access, absolute time and position information, access to an

SD card, and the ability to control a small display.

If you do not have any of these devices, and wish to recover the logic used

by them, you may comment out the defines for {\tt GPS\_CLOCK},

{\tt SDCARD\_ACCESS}, and {\tt OLEDRGBACCESS} found in the {\tt rtl/busmaster.v}

file.  This will recover all but the logic used by the PModUSBUART and PModGPS

serial ports, while replacing the registers with read--only memory values of

zero.

\section{Testing the peripherals}

OpenArty has been designed so that all of the peripherals live on a

memory--mapped wishbone bus.  This bus can be accessed, either by the ZipCPU

or by the host controller.  Because of this model, peripherals may be tested

and known to work before the CPU is ever turned on.  Two programs make this

possible: netuart and wbregs.  Other programs may be built upon this model,

as long as they access the bus using the interface outlined in devbus.h.

Of the two programs, netuart simply turns the USB serial port interface of

the device into a TCP/IP interface.  Netuart takes one argument, the

name of the serial port device which the Arty USB driver has created.  In

my case, this tends to be /dev/ttyUSB1, although it has been known to change

from time to time:

\begin{lstlisting}[language=bash]

% netuart /dev/ttyUSB1

\end{lstlisting}

All of the other board support files connect to the TCP/IP port generated

by netuart.  The port.h file is a compiled-in file, outlining where this

port can be found.  By default, netuart listens to port {\tt 6510} on

{\tt localhost}, but it can be configured to listen to any port.  The other

board support files will try to connect to netuart at the host and port

listed in port.h.  Hence, if properly configured, you should be able to

access your Arty to command it, configure it, reload it, etc., from anywhere

you have internet access--in my case, from anywhere in the house.

Once you run netuart, you should then be able to watch, as a part of the

standard output stream of netuart, all of the interaction with the board.

While this may be useful for debugging, it's not all that legible to the

user.   Lines that start with \hbox{``\#''} are lines from the device that are not

going to any client.  A common line you will see is \hbox{``\# 0''}.  This is

just the device saying that its command capability is idle.  Lines that start

with \hbox{``< ''} are commands going to the device, and lines starting with

\hbox{``> ''} are responses from the core.  So, at this point, run netuart and

wait a couple of seconds.  If you do not see a \hbox{``\# 0''} line, then try a

different serial port, check that your core is properly configured, etc.  Once

you do see a \hbox{``\# 0''} line, then you are ready for the next step.

The easiest way to test the peripherals is via the wbregs command.  This

command is similar to the ancient peek and poke commands.  It takes one

or two arguments.  If given one argument, it reads from that address on the

bus.  If given two arguments, it writes the value of the second argument to

the bus location given by the first argument.  Hence one argument peeks

at the memory bus, two arguments pokes a value onto the memory bus.

Perhaps an example will help.  At this point, try typing:

\begin{lstlisting}[language=bash]

% wbregs version

\end{lstlisting}

This should return and print a 32-bit hexadecimal value to your screen,

indicating the date of when you last ran make in the root directory before

building and installing your configuration into the device.  This can be

very useful to know what configuration you are running, and whether or not

you have made the changes you thought you had made.

You may have noticed that wbregs read from address 0x0100, but did so by name.

Most of the peripherals have names for their addresses.  The C language

names for these addresses can be found in regdefs.h, and a mapping to

wbregs address names can be found in regdefs.cpp.

Shall we try another?  Let's try adjusting the LEDs.  To turn all the LEDs off,

\begin{lstlisting}[language=bash]

% wbregs leds 0x0f0

\end{lstlisting}

To turn them all back on again,

\begin{lstlisting}[language=bash]

% wbregs leds 0x0ff

\end{lstlisting}

To turn the low order LED off without changing any others, write

\begin{lstlisting}[language=bash]

% wbregs leds 0x010

\end{lstlisting}

Having fun?  Try running the program startupex.sh from the sw directory.

This will set some LEDs and Color LEDs in a fun, startup--looking, pattern.

Ready to test the UART?   Using minicom, connect to the PModUSBUART.  It

should also be connected to a /dev/ttyUSBx serial port device.  If you aren't

sure, start minicom with:

\begin{lstlisting}[language=bash]

% minicom -D /dev/ttyUSB2

\end{lstlisting}

Then, configure minicom to use 115,200 Baud, 8-data bits, one stop bit, and

no parity.

Once you've done that, we can test it by sending a character across the UART

port:

\begin{lstlisting}[language=bash]

% wbregs tx 90

\end{lstlisting}

This should send a `Z' over the UART port.  Did you see a `Z' in minicom?

If not, did you set the baud rate right?  The UART is supposed to be set

for 115,200 Baud, 8N1 by default.  If not, you can set it to that by writing

wbregs setup 705.  The 705 comes from the clock rate, in Hz, divided by

115200.  By leaving other higher order bits at zero, this becomes the default

baud rate of an 8N1 serial port channel.

Another fun program to run is {\tt netsetup}.  This program takes no arguments,

and just reads and decodes the network registers via the MDIO port.  The

decoded result will be sent to the screen.

\section{Subsequent Core Updates}

The board support file {\tt wbprogram} can be used to write .bit or .bin

files to the flash, so that the core can be updated once an initial core

is installed and running.

Although wbprogram expects the filename to end in either '.bit' or '.bin',

this is primarily to keep a user from doing something they don't intend to

do.

The basic usage of the wbprogram command is:

\begin{lstlisting}[language=bash]

% wbprogram [@address] file

\end{lstlisting}

wbprogram then copies the file to the flash, starting at the Arty address

of {\tt @address}.  If no address is given, wbprogram writes the file at the

beginning of flash.

An example of how to do this can be found in the {\tt program.sh}.

{\tt program.sh} places the new configuration file into the alternate

configuration location.  (An alternate script, zprog.sh, places the new

configuration at the beginning of the flash, where the FPGA loader will look

for it upon power up.)  Once {\tt program.sh} places the new configuration

into flash, it then commands the FPGA via the ICAPE2 interface and an IPROG

command to reconfigure itself using this new configuration.  As a result, this

can be used to load subsequent configurations into the FLASH.

\section{Building the ZipCPU tool-chain}

At this point, you should have some confidence that your configuration and

hardware are working.  Therefore, let's transition to getting the ZipCPU

on the hardware up and running.  To do this, we'll start with getting a copy

of the ZipCPU toolchain and building it.  Pick a directory to work in, and

then issue:

\begin{lstlisting}[language=bash]

% git clone https://github.com/ZipCPU/zipcpu

\end{lstlisting}

to get a copy of the ZipCPU project, together with toolchain, and then

in the master directory, type:

\begin{lstlisting}[language=bash]

% cd zipcpu; make

\end{lstlisting}

(you may need to issue the make command a couple of times \ldots)

This will build the GCC compiler for the ZipCPU from source.

It will also install this new compiler into the zipcpu/sw/install/cross-tools.

This new compiler will be called zip-gcc.

This will also build a copy of the binutils programs for the ZipCPU.  These

include the assembler, {\tt zip-gas}, linker, {\tt zip-ld}, disassembler,

{\tt zip-objdump}, and many more useful programs.

The next step to using this toolchain is to place it into your path.

\begin{lstlisting}[language=bash]

% export PATH=$PATH:$PWD/zipcpu/install/cross-tools/bin

\end{lstlisting}

Once the toolchain is in your path,

\begin{lstlisting}[language=bash]

% which zip-gcc

/home/.../zipcpu/sw/install/cross-tools/bin/zip-gcc

\end{lstlisting}

should return the location of where this toolchain exists in your path.

\section{Building your first ZipCPU program}

Several example programs for the OpenArty project can be found in the

{\tt sw/board} directory.  These can be used to test various peripherals from

the perspective of the CPU itself.

As a test of the build process, a good first progam to build would be

{\tt exstartup}.  This program is very similar to the {\tt startupex.sh} shell

script you tried earlier.  It simply plays with the color LEDs and some

on board timers.   Once that is finished, it goes into a loop controlling

both the normal and the color LEDs based upon the button state and the switch

settings.

To build {\tt exstartup}, simply type {\tt make exstartup} from the

{\tt sw/board} directory of the {\tt openarty} project.  (Don't forget to

include the ZipCPU toolchain into your path before you do this!)

\section{Loading a program}

Now that you have built your {\tt exstartup} program, it's time to load it

onto the board and start it up.  The {\tt zipload} program can be used to

do this.  {\tt zipload} can be found in the sw/host directory.  To load a

ZipCPU program into the Arty, just type {\tt zipload} and the program name,

such as {\tt exstartup} in this case.  To start the program immediately

after loading it, pass the `-r' option to {\tt zipload}.  In our case, you

would type:

\begin{lstlisting}[language=bash]

% zipload -r exstartup

\end{lstlisting}

Hopefully, you can see the {\tt exstartup} program now toggling the LED's.

Once the initial display stops, you can adjust the switches and press buttons

to see how that affects the result.

If you wish to restart the {\tt exstartup} program, or indeed to run another

program, you can just run {\tt zipload} again with the new program name.  This

will halt the previous program, and then load the new one into memory.  As

before, if you use the `-r' option, the program will be started automatically.

\section{Some other test programs}

If you have the PModUSBUART, you might wish to try running a ``Hello, World''

program.  This can be found in the hello.c file.  It prints ``Hello, World''

to the PModUSBUART once every ten seconds.  Had enough of it?  You can stop

the CPU by typing {\tt wbregs cpu 0x0400}.  This sends a halt command to the

debug register of the ZipCPU.  More information about this debug register, and

other things that can be done via the debug register, can be found in the

ZipCPU specification.

If you have both the PModUSBUART as well as the PModGPS, the {\tt gpsdump.c}

program can be used to forward the NMEA stream from the GPS to the USBUART.

This should give you some confidence that the PModGPS is working.

As a third test, {\tt oledtest.c} will initialize the OLEDrgb device and cause

it to display one of two images in an alternating fashion.

block RAM, the SDRAM, and the Ethernet TX buffer, as well as read only memory

regions, such as the flash memory and the Ethernet RX buffer, as well as a

whole lot of memory mapped peripherals.  The purpose of this chapter will be

to describe how these memory mapped peripherals are organized, as well as

the specific details of how they may be used.

This address map information is also contained in a couple other locations.

First, {\tt sw/host/regdefs.h} maps all of the OpenArty registers to

C++ names, whereas {\tt sw/host/regdefs.cpp} maps these C++ names to a more

human readable form which is used by {\tt wbregs}.  Second, these registers

are also given names as part of several various structures within

{\tt sw/board/artyboard.h}.  And then, of course, they are also listed here.

\section{ZipSystem}

The ZipSystem wrapper around the ZipCPU provides access to roughly twenty

registers that are tightly integrated with the ZipCPU.  These registers are

shown in Tbl.~\ref{tbl:zipio}

and described in detail within the ZipCPU specification.

Unlike the rest of the address map, these registers are only visible to the

ZipCPU.  While many of them may be read via the debug port, in general accessing

these registers via the {\tt wbregs} command is not so straight forward.

{\tt 0x100}.  These peripherals are specifically peripherals that can be

accessed without ever stalling the bus, and with a known and fixed (minimum)

delay.  Tbl.~\ref{tbl:ioregs}

\subsection{Version}

One of the simpler peripherals on the board is the {\tt VERSION} peripheral.

This simple returns the date stamp found within {\tt rtl/builddate.v}.  This

stamp is updated any time a {\tt make} command is issued in the main OpenArty

project directory.  Reads from this address return this value, writes to this

address are ignored.

This peripheral is {\em very} useful, especially when trying to determine which

version of your configuration you are using, and whether or not the

configuration has been changed or updated as you had intended by loading a new

configuration, by writing a configuration to the flash and issuing an IPROG

command, etc.

interrupt controller.

Hence, even though the CPU only supports a single interrupt line, by cascading

it with a second controller, many more interrupts can be supported.

The third interrupt controller is the bus interrupt controller.  While the

CPU can read and write this controller, the interrupt line from this controller

goes to the host interface.  If you see, as an example, an \hbox{``> 4''} in

your {\tt netuart} window, then you will know that OpenArty has sent an

interrupt to a waiting host program.  If what you saw instead was a

\hbox{``\# 4''}, then the interrupt was sent, but no one was listening.

mask that would need to be used when referencing them to the interrupt

controller.  In a similar fashion, the auxilliary interrupt controller accepts

inputs from the sources listed in Tbl.~\ref{tbl:aux-ints}.

These interrupt mask constants are also defined in {\tt sw/board/artyboard.h}

and {\tt sw/board/zipsys.h}.

Finally, the bus interrupt controller handles the interrupts from the sources

listed in Tbl.~\ref{tbl:bus-ints}.

You may notice that there is a lot of overlap between these interrupt sources.

That is so that the host can also receive many of the same interrupts the ZipCPU

can receive.

Should an attempt be made to access a non--existant memory address, or should

multiple devices all return their data at the same time on the bus, a bus

error will be created.  When and if this happens, the address on the bus

when this error was created will be placed into the last bus error address.

This is the only way to set this address.

\subsection{Power counter}

Some peripherals may require a certain amount of time from power up or startup

until they can be accessed.  Guaranteeing this amount of time is the purpose

of the power counter.  This simple read only register simply counts up from

zero on every clock, with the exception that once the high order bit is set

then it is never cleared.

\subsection{Button and Switch Register}

btn-now / 4'h0 / btncfg / swcfg / btnstate / swstate

The button and switch register includes a variety of fields for reading the

current state of the buttons and switches, and for controlling the two related

interrupts.  The register is separated into several fields, however, as shown

in Fig.~\ref{fig:btnsw}.

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

\bitheader{0-31}\\

\bitbox{8}{\em Ignored}

\bitbox{4}{BNOW}

\bitbox{4}{4'h0}

\bitbox{4}{BCFG}

\bitbox{4}{SCFG}

\bitbox{4}{BTN}

\bitbox{4}{SW}

\end{bytefield}

\caption{Button/Switch register layout}\label{fig:btnsw}

\end{center}\end{figure}

The current state of the buttons and switches can be read through the {\tt BNOW}

and {\tt SW} bit--fields.

The {\tt BTN} field contains one bit per button.  When a button is pressed,

the respective bit in this field will be set.  It will then remain set until

cleared.  To clear a value in this bit--field, write a `1' to the position you

wish to clear.

Then {\tt BCFG} field controls which buttons will trigger a button interrupt.

Should a button be pressed while its corresponding value within this field

is a `1', a button interrupt pulse will be issued.  To set a bit within this

field, you need to not only write the corresponding bit value, but you must

also set an enable bit within the {\tt BTN} field.  Hence, writing a

{\tt 0x0f0f0} will set all of the bits within this field, while {\tt 0x0f000}

will have no effect, and {\tt 0x0030} will clear two bits.  Notice also that,

when clearing a button press from the {\tt BTN} bits, the corresponding

{\tt BCFG} bits will also be cleared.

Finally, the {\tt SCFG} field controls whether or not changing a switch value

will cause an interrupt.  As with the {\tt BCFG} field, changing a value

in this register requires writing to the {\tt SW} field as an enable.

The use of the enable bit--field lines was added so that reads and writes to

this register wouldn't need special atomic access protections, so that some

configuration bits could be changed without setting all of them, and so that

changes during writes wouldn't go unnoticed.

\subsection{LED control register}

The LED control register has a layout similar and enable field similar to that

of the button/switch control register.  These fields can be seen in

Fig.~\ref{fig:ledctrl}

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

\bitheader{0-31}\\

\bitbox{24}{\em Ignored}

\bitbox{4}{ENB}

\bitbox{4}{LED}

\end{bytefield}

\caption{LED control register layout}\label{fig:ledctrl}

\end{center}\end{figure}

The bottom four {\tt LED} bits of this register will always contain the current

state of the LEDs.  To change an LED's state, write to this register the new

state with the corresponding {\tt ENB} (enable) bit set.  Hence writing a

{\tt 0x0c0} will turn off LED's two and three, while writing a {\tt 0x033} will

set LED's zero and one, and writing a {\tt 0x0f} will be ignored.

\subsection{UART setup registers}

There are two UART setup registers: one for controlling the PModUSBUART setup

and the other for controlling the PMod GPS NMEA UART.  These follow the format

given in the {\tt wbuart32} project, with a bit field shown in

Fig.~\ref{fig:uartsetup}.

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

\bitheader{0-31}\\

\bitbox{2}{00}

\bitbox{2}{N}

\bitbox{1}{S}

\bitbox{1}{P}

\bitbox{1}{F}

\bitbox{1}{T}

\bitbox{24}{Clocks per Baud}

\end{bytefield}

\caption{UART setup register format}\label{fig:uartsetup}

\end{center}\end{figure}

In general, the only control needed to set these registers is to set their

baud rate based upon the number of clocks per baud.  Hence, to set a

9600~baud rate, given an 82.5~MHz clock rate, one would set this register to

{\tt 8594}.  The high order bits are designed so that writing a zero to them

sets the interface for 8--data bits, no parity, and one stop bit.

The number of data bits may be adjusted by changing the $N$ field from zero,

for eight data bits, on up to three, for five data bits.

The $S$ bit determines whether or not the system will insert and require an

extra stop bit.  Setting it to zero sets the system to require only a single

stop bit.

The $P$ bit controls whether or not parity is enabled, and the $F$ bit controls

whether or not the parity is fixed.  $T$ controls what type of parity is then

used.  By setting $P$ to zero, parity checking and generation is turned off.

Finally, the auxiliary UART (i.e. the PMod USBUART) defaults to 115,200 Baud,

8N1, whereas the GPS UART defaults to 9600 Baud, 8N1.  Both may be adjusted

via this register.

\subsection{Color LED registers}

Since the Arty has four color LEDs, the OpenArty has four register words to

control those LEDs.  These registers are split into three bit fields, an

8--bit red, 8--bit green, and an 8--bit blue bit field.  The top eight bits

are ignored.  Unlike many of the other OpenArty registers, these bit fields

may be read or written with no special enable values.

\subsection{RTC date register}

The real--time--clock date register format is shown in Fig.~\ref{fig:rtcdate}.

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

\bitheader{0-31}\\

\bitbox{16}{Year}

        \bitbox{8}{Month}

        \bitbox{8}{Day}\\

\bitbox{4}{Y}

        \bitbox{4}{Y} \bitbox{4}{Y} \bitbox{4}{Y}

\bitbox{4}{M} \bitbox{4}{M}

\bitbox{4}{D} \bitbox{4}{D}\\

\end{bytefield}

\caption{RTC Date register layout}\label{fig:rtcdate}

\end{center}\end{figure}

This is also a very simple register, containing eight binary coded decimal

(BCD) digits.  Due to the nature of this setup, the date can be read quickly

from the hexadecimal value of the register, and dates can be compared validly

to determine if a date is earlier or later than any other.  Writes to the

date register will set the date, otherwise the date will automatically

increment whenever the Real Time Clock rolls over into the next day.

Unlike the Linux {\tt ctime} system call, the month value ranges from

one to twelve.  The day of the month ranges from 1~to 31, or whatever is

appropriate for the current month.

The General Purpose I/O controller will be the same as the controller from the

S6~SoC once installed.

\subsection{UART Data Registers}

Each of the two UARTs, PMod USBUART and PMod GPS, has two data registers and

two interrupts associated with it: one for receive and one for transmit.

As with the rest of the Arty I/O design, these are designed so that unused

extra bits will be zero, and can (usually) quietly be ignored.

The receive UART register format is shown in Fig.~\ref{fig:rxuart}.

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

\bitheader{0-31}\\

\bitbox{20}{\em Always zero}

\bitbox{1}{B} \bitbox{1}{F} \bitbox{1}{P} \bitbox{1}{I}

\bitbox{8}{Data}\\

\end{bytefield}

\caption{Receive UART register layout}\label{fig:rxuart}

\end{center}\end{figure}

This register may only be read, writes are silently ignored.  If no receive

value is present, the $I$ bit will be set.  If either a parity error, $P$, or

frame error (stop bit not high), $F$, have occurred, those respective bits will

be high.  The error bits are cleared upon successfully receiving a word across

the interface.  Finally, the $B$ bit indicates the line is in a {\tt BREAK}

condition.

The interface has been designed for one of two means of accessing it.  The

interface may be polled.  In that case, anding the result with {\tt 0x0f00}

will tell whether the result is invalid.  The interface may also be read upon

a receive interrupt.  In that case, the same bit fields apply, but the $I$ bit

will be guaranteed to be low.  Finally, the interrupt line will continue

generating an interrupt input to the interrupt controller until it has been

read.  Therefore, handling receive UART interrupts requires reading the receive

data and then resetting the interrupt controller.  This also means, though, that

the receive port should work quite well with the DMA controller.

As currently implemented, neither transmit nor receive UARTs have attached

FIFOs.  Hence, once a value is ready to be read, it must be read before the

next value is available to be read.

The transmit UART register is shown in Fig.~\ref{fig:txuart}.

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

\bitheader{0-31}\\

\bitbox{20}{\em Always zero}

        \bitbox{1}{R}

        \bitbox{1}{O}

        \bitbox{1}{B}

        \bitbox{1}{S}

        \bitbox{8}{Data}\\

\end{bytefield}

\caption{Transmit UART register layout}\label{fig:txuart}

\end{center}\end{figure}

Of these bits, the data register is the most important.  Writes to the transmit

UART, with only the bottom eight bits set, will send those bits out the

data port.  Writes with the $B$, or {\tt BREAK} bit, set will place the

transmitter into a {\tt BREAK} condition.  This condition is only cleared by

writing with the $B$ bit clear.  The $S$ bit is a read-only busy bit, true if

the device is still busy sending the last character.  Finally, the $R$ and $O$

bits reflect the current value read on the receive port and the current value

being placed onto the transmit port respectively.

As with the receive register, the transmit register has been designed to either

be used in a polling or interrupt fashion.  When polled, the $S$ bit may be

checked to determine if the transmitter is still busy sending the last

character.  When the $S$ bit is clear, the UART transmitter will be responsive

to another character written to it.  In interrupt mode, the device will

constantly trigger an interrupt into the interrupt controller whenever  it is

idle.  As with the receive, the only way to reset this interrupt is to send

a character and then reset the bit in the interrupt controller.

\subsection{System seconds counter}

As part of tracking the current time, it is important to have an accurate

seconds counter that increments with every second.  That's what this register

provides.  This plus the subsecond register should be the current time.

The problem is setting this register.  While the subsecond time register can be

set using the PPS signal from the GPS, this seconds register will need to be

calculated from the NMEA data stream.  To make this work, this register has been

set up so that not only does it increment by one on the top of any second, but

when written to the register will be bumped by whatever value is written to it.

Hence, to step it forward by a second, write a {\tt 32'h1} to it.  To step it

backwards, write a {\tt 32'hffffffff}.

\subsection{GPS Subsecond time}

As part of being able to provide highly accurate time resolution, it is

important to be able to read the current time at any given time.  This

register provides the sub--seconds value associated with the current time.

It is specifically the amount of time since the top of the last second

times $2^{32}$.  As such, it rolls over at the top of each second.  The

top bit can be used as an indication of the second half of the second, etc.

\subsection{GPS derived clock step}

This 32--bit value is closely related to the sytem clock frequency.  It is a

{\tt step} value designed so that a $2^{48}$ bit counter, incremented by this

{\tt step} value on every clock tick, will roll over after one second.  To

convert this to the GPS derived clock frequency, apply the formula:

\begin{eqnarray}

f_{\mbox{\tiny CLK}} &=& \frac{2^{48}}{\mbox{\tt STEP}}

\end{eqnarray}

The real--time clock controller is part of the {\tt rtcclock} project which

should also be found near this distribution.  The manual for that project

should describe the four registers, clock, timer, stopwatch, and alarm, that

can be controlled herein.

\section{SD Card controller}

% TODO write something more meaningful

The SD card controller is part of the {\tt sdspi} project which

should also be found near this distribution.  The manual for that project

should describe the four registers, control, data, and the two FIFO's registers,

that can be controlled herein.

\section{GPS PPS Tracking Loop control}

The coefficients for the PLL that tracks the GPS PPS can be controlled via the

registers listed in Tbl.~\ref{tbl:gpsctrl}.

\begin{table}

\begin{center}\begin{reglist}

alpha  &\scalebox{0.8}{\tt 0x0130} & 8 & R/W & Recursive Error Averaging Coefficient\\\hline

beta   &\scalebox{0.8}{\tt 0x0131} & 32 & R/W & Phase Tracking Coefficient\\\hline

gamma  &\scalebox{0.8}{\tt 0x0132} & 32 & R/W & Frequency Tracking Coefficient\\\hline

defstep&\scalebox{0.8}{\tt 0x0133} & 32 & R/W & Default clock step\\\hline

\end{reglist}

\caption{GPS PPS Tracking Control Registers}\label{tbl:gpsctrl}

\end{center}\end{table}

\section{GPS testbench info}

The GPS PPS tracking core found within the Arty was originally tested using

a GPS testbench.  Since simulation and performance measurement was a chalelnge,

that testbench has been given a permanent place within the Arty.  Within it,

there are eight registers, grouped into five variables.  These registers are

designed so that, if read in a burst fashion, none of the registers will

change during the burst--guaranteeing their coherency.

The first two registers will be ignored, unless specifically enabled by

defining {\tt GPSTB} in busmaster.v.  They are designed to see how the

GPS tracking circuit will respond to an absolutely accurate input.  The

first, the {\tt tb\_maxcount} value, sets the number of clocks per simulated

PPS tick.  The second, the {\tt tb\_jump} value, when written to will cause

the PPS to suddenly be displaced in phase by the value written.  Both of these

are ignored unless the test bench was configured to produce a simulated

PPS signal.

The third register is the 64--bit error.  Specifically, this is the value of

the GPS step counter at the top of the second.  In a perfect world, with

perfect tracking, it should be zero.  In a wonderful world with nearly perfect

tracking, this register should be less than the GPS step size.

The fourth register is the 64--bit count register.  This indicates the current

time, in 64--bit precision.  The top 32--bits of this register are the same

as the sub--seconds register presented earlier.

The final register is the 64--bit step register.  This register is very similar

to the 32--bit {\tt STEP} register discussed earlier.  It is designed so that,

when multiplied by the clock frequency in Hertz, the result should equal

$2^{64}$.  The register, though, captures the current state of the GPS tracking

circuit's estimate of the clock speed of the processor in this fashion.

\section{OLEDrgb control}

The OLEDrgb can be controlled by four registers, listed in

Tbl.~\ref{tbl:oledctrl}.

\begin{table}

\begin{center}\begin{reglist}

CTRL &\scalebox{0.8}{\tt 0x0130} & 32 & R/W & Control register\\\hline

REGA &\scalebox{0.8}{\tt 0x0131} & 32 & R/W & First excess control word\\\hline

REGB &\scalebox{0.8}{\tt 0x0132} & 32 & R/W & Second excess control word\\\hline

DATA &\scalebox{0.8}{\tt 0x0133} & 32 & R/W & Data and power register\\\hline

\end{reglist}

\caption{OLED Control Registers}\label{tbl:oledctrl}

\end{center}\end{table}

The first three are used to send information across the control port of the

OLEDrgb, the last is used to adjust the power, reset, and I/O line voltage,

as well as to send data values to the device.

Unlike the flash, network MDIO registers, or ICAPE port, reads and writes

of this device will not stall the wishbone bus, and will complete immediately.

Commands issued to the device while the controller is busy will therefore be

quietly ignored.

Working with the device starts by powering it up.  This sequence is given

by the manufacturer, and it requires the use of data register.  This data

register has one of two interpretations, as shown in Fig.~\ref{fig:odata}.

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

\bitheader{0-31}\\

        \bitbox{16}{16'h00}

        \bitbox{16}{Data}\\

\bitbox{13}{13'h00}

        \bitbox{1}{R} \bitbox{1}{V} \bitbox{1}{E}

        \bitbox{13}{13'h00}

        \bitbox{1}{R} \bitbox{1}{V} \bitbox{1}{E} \\

\end{bytefield}

\caption{OLED data register: Data write format, and power control read/write format}\label{fig:odata}

\end{center}\end{figure}

In the first interpretation, data may be sent to the port by simply

writing that data to the port, while leaving the top sixteen bits zero.

(We'll get to this later.)  In the second interpretation, the reset and

power bits may be adjusted by setting the upper bit high (an enable bit),

together with the corresponding lower bit to the value desired.

The $R$ bit will be zero if the device is in a reset state (an active low

reset).  The $V$ bit is one if the VCC output is enabled.  The $E$ bit is one

if the PMod is enabled, otherwise the power to the PMod is cut.  Adjusting

these bits requires writing a `1' to the bit you wish to change, and then

at the same time writing the value you wish to change it to in the lower order

bits.  Hence writing a {\tt 0x010001} to the device will turn the power on,

whereas a {\tt 0x010000} will turn it off.  Likewise {\tt 0x040000} will place

the device into reset (active low), and {\tt 0x040004} will release the reset

line.

Reads from this port simply return the current values of the $R$, $V$, and

$E$ bits in the least significant 3--bits.

The power--up sequence for the device is shown below:

\begin{enumerate}

\item Wait a quarter second from configuration start

\item Power up the device, writing a {\tt 0x050005} to the data port to

        power up, but without setting the reset line yet.

\item Wait four microseconds.

\item Activate the reset line, by writing a {\tt 0x040000} to this data port.

\item Wait another four microseconds.

\item Clear the reset, by writing a {\tt 0x040004} to this data port.

\item Wait another four microseconds.

\item Initialize the display.

\end{enumerate}

At this point, a series of commands need to be sent to the devices control

port.  These commands are written to the control register.  The control

register accepts several different types of writes, as shown in

Fig.~\ref{fig:octrl}.

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

\bitheader{0-31}\\

        \bitbox{24}{24'h00}

        \bitbox{8}{8'data}\\

\bitbox{15}{15'h00}\bitbox{1}{1}\bitbox{16}{16'data} \\

\bitbox{4}{4'h2}\bitbox{4}{}\bitbox{24}{24'data} \\

\bitbox{4}{N-1}\bitbox{4}{}\bitbox{24}{24'data} \\

\end{bytefield}

\caption{Four separate OLED control register write formats}\label{fig:octrl}

\end{center}\end{figure}

To send a single byte of data, write that byte to the control port.

Two bytes require setting bit sixteen, and they are sent high order byte first.

Sending three or more bytes requires setting the number of bytes you wish to

send, $N$, minus one to the top four bits, followed by the first three bytes,

high order byte first.  To send longer commands, place the next four bytes

into register {\tt A}, and the next four after that into register {\tt B}.

In this manner, the device can send commands of up to 11~bytes in length,

although most commands may be sent and received with writing only a single

word to the control port.

The actual set of commands used to initialize the display is rather complex.

Please examine the {\tt oledtest.c} ZipCPU program for an example of how

this might be accomplished.  That program sends a series of commands to the

control port, waiting for the port to become idle inbetween.  When using polled

I/O, the low order bit of the control register will be `1' if the port is busy,

zero if not.

\section{Internal Configuration Access Port}