OpenCores
URL https://opencores.org/ocsvn/wbuart32/wbuart32/trunk

Subversion Repositories wbuart32

[/] [wbuart32/] [trunk/] [doc/] [src/] [spec.tex] - Blame information for rev 15

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 2 dgisselq
\documentclass{gqtekspec}
2
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3
%%
4
%% Filename:    spec.tex
5
%%
6
%% Project:     wbuart32, a full featured UART with simulator
7
%%
8
%% Purpose:     To describe, for LaTeX, how to build the specification file
9
%%              for the wbuart32 core(s).  This file is not nearly as
10
%%      interesting as the file it creates, so I suggest you read spec.pdf
11
%%      first, before deciding you are really interested in this file.
12
%%
13
%% Creator:     Dan Gisselquist, Ph.D.
14
%%              Gisselquist Technology, LLC
15
%%
16
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
17
%%
18
%% Copyright (C) 2015-2016, Gisselquist Technology, LLC
19
%%
20
%% This program is free software (firmware): you can redistribute it and/or
21
%% modify it under the terms of  the GNU General Public License as published
22
%% by the Free Software Foundation, either version 3 of the License, or (at
23
%% your option) any later version.
24
%%
25
%% This program is distributed in the hope that it will be useful, but WITHOUT
26
%% ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY or
27
%% FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
28
%% for more details.
29
%%
30
%% You should have received a copy of the GNU General Public License along
31
%% with this program.  (It's in the $(ROOT)/doc directory, run make with no
32
%% target there if the PDF file isn't present.)  If not, see
33
%% <http://www.gnu.org/licenses/> for a copy.
34
%%
35
%% License:     GPL, v3, as defined and found on www.gnu.org,
36
%%              http://www.gnu.org/licenses/gpl.html
37
%%
38
%%
39
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
40
%%
41
%%
42
\usepackage{import}
43
\usepackage{bytefield}
44
\usepackage{amsmath}
45
\project{WBUART32}
46
\title{Specification}
47
\author{Dan Gisselquist, Ph.D.}
48 5 dgisselq
\email{dgisselq (at) ieee.org}
49 12 dgisselq
\revision{Rev.~1.0}
50 2 dgisselq
\begin{document}
51
\pagestyle{gqtekspecplain}
52
\titlepage
53
\begin{license}
54 5 dgisselq
Copyright (C) 2016--2017, Gisselquist Technology, LLC.
55 2 dgisselq
 
56
This project is free software (firmware): you can redistribute it and/or
57
modify it under the terms of  the GNU General Public License as published
58
by the Free Software Foundation, either version 3 of the License, or (at
59
your option) any later version.
60
 
61
This program is distributed in the hope that it will be useful, but WITHOUT
62
ANY WARRANTY; without even the implied warranty of MERCHANTIBILITY or
63
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
64
for more details.
65
 
66
You should have received a copy of the GNU General Public License along
67
with this program.  If not, see \texttt{http://www.gnu.org/licenses/} for a copy.
68
\end{license}
69
\begin{revisionhistory}
70 12 dgisselq
1.0 & 2/20/2017 & D. Gisselquist & Added Hardware Flow Control\\\hline
71 5 dgisselq
0.2 & 1/03/2017 & D. Gisselquist & Added test-bench information\\\hline
72 2 dgisselq
0.1 & 8/26/2016 & D. Gisselquist & Initial Draft Specification\\\hline
73
\end{revisionhistory}
74
% Revision History
75
% Table of Contents, named Contents
76
\tableofcontents
77
\listoffigures
78
\listoftables
79
\begin{preface}
80
It may be that building a UART is a mandatory coming of age task for any HDL
81
designer.  The task is simple, easy, and there's not all that much to it.
82
This project comes out of some of my first experiences with Verilog.
83
 
84 5 dgisselq
Since then, it has been augmented with quite a few useful capabilities for
85 2 dgisselq
simulating a UART connection when using Verilator.  It is this, perhaps
86
unusual, addition to the core set that makes this core worth taking note of.
87
 
88
I hope you find it useful.
89
\end{preface}
90
 
91
\chapter{Introduction}\label{ch:intro}
92
\pagenumbering{arabic}
93
\setcounter{page}{1}
94
%
95
% Introduction
96
%
97
% This section contains the introduction to the core, describing both its
98
% use and its features.
99
%
100
 
101
% What is old
102
The Universal Asynchronous Serial Transport, or UART, has become quite the
103
common protocol between devices.  It is simple to wire up, easy to use, and
104
easy to process.  This core provides one implementation of the logic necessary
105
to use such a communications scheme.
106
 
107
% What does the old lack?
108
% What is new
109
% What does the new have that the old lacks
110
% What performance gain can be expected?
111
 
112
While you are likely to find many UART examples out there, this particular
113
UART implementation offers something many of these other examples do not: a
114
Verilator simulation capability.  This will allow the user to connect, via
115
a TCP/IP port or a telnet application, to the UART of their desired chip.  As
116
a result, full two-way interaction can be had between a simulation and a
117
terminal or other port.  Indeed, this may even be sufficient to connect a
118
CPU, capable of running Linux, to a terminal to verify that yes it can truly
119
run Linux--all within Verilator.
120
 
121 12 dgisselq
As a final addition, there are four files in the test bench section which can
122 5 dgisselq
be used as top--level design files to prove whether or not the serial port on
123
a given circuit board works.
124
 
125 2 dgisselq
\chapter{Architecture}\label{ch:arch}
126
 
127 5 dgisselq
The HDL portion of the core itself consists of four basic files: {\tt rxuart.v},
128
{\tt txuart.v}, {\tt ufifo.v} and {\tt wbuart.v}.  These are, respectively, the
129
receive UART code, the transmit UART code, a fairly generic FIFO, and a fully
130 12 dgisselq
wishbone compliant UART peripheral.  This latter file demonstrates one example
131
of how the receiver, transmitter, and a pair of FIFOs may be connected to a
132
Wishbone bus.  A fifth file, {\tt wbuart-insert.v}, demonstrates how the
133
{\tt rxuart.v} and {\tt txuart.v} files may be included into a module
134
implementing a simpler wishbone interface without the FIFO.
135 2 dgisselq
 
136
Each of the core files, {\tt rxuart.v} and {\tt txuart.v}, are fully capable.
137 12 dgisselq
They each accept a 30--bit setup value specifying baud rate, the number of bits
138
per byte (between 5 and 8), whether hardware flow control is off, or whether or
139
not parity is used, and if so whether that parity is even, odd, or fixed mark
140
or fixed space.  This setup register will be discussed further in
141
Chap.\ref{ch:registers}.
142 2 dgisselq
 
143
A further note on the {\tt rxuart.v} module is in order.  This module double
144
latches the input, in the proper two buffer fashion to avoid problems with
145
metastability.  Then, upon the detection of the start bit (i.e. a high to low
146
transition), the port waits a half of a baud, and then starts its baud clock
147
so as to sample in the middle of every baud following.  The result of this is
148
a timing requirement: after $N+2$ baud intervals ($N+3$ if parity is used),
149
where $N$ is the number of bits per byte, this calculated middle sample must
150
still lie within the associated bit period.  This leaves us with the criteria
151
that,
152
\begin{eqnarray}
153
\left|\left(N+2\right)
154
        \left(\frac{f_{\mbox{\tiny SYS}}}{f_{\mbox{\tiny BAUD}}}
155
                -{\mbox{\tt CKS}}\right)\right|
156
        &<& \frac{f_{\mbox{\tiny SYS}}}{2f_{\mbox{\tiny BAUD}}},
157
        \label{eqn:baudlimit}.
158
\end{eqnarray}
159
where $f_{\mbox{\tiny SYS}}$ is the system clock frequency,
160
$f_{\mbox{\tiny BAUD}}$ is the baud rate or frequency,
161
{\tt CKS} is the number of clocks per baud as set in the configuration
162
register, and $N$ is the number of bits per byte.  What this means is that,
163
for transmission rates where $f_{\mbox{\tiny BAUD}}$ approaches
164
$f_{\mbox{\tiny SYS}}$, the number of data rates that can actually be
165
synthesized becomes limited.
166
 
167
Connecting to either {\tt txuart.v} or {\tt rxuart.v} is quite simple.  Both
168
files have a data port and a strobe.  To transmit, set the data and strobe
169 12 dgisselq
lines.  Drop the strobe line on the clock after the busy line was low.
170 5 dgisselq
Likewise, to connect to the {\tt rxuart.v} port, there is a data
171
and a strobe.  This time, though, these two wires are outputs of the receive
172
module as opposed to inputs.
173 2 dgisselq
When the strobe is high, the data is valid.  It will only be high for one
174
clock period.  If you wish to connect this output to a bus, a register will be
175 12 dgisselq
needed to hold the strobe high until the data is read, as in
176
{\tt wbuart-insert.v}.  Also, while the strobe
177 5 dgisselq
is high, the {\tt o\_frame\_err} will indicate whether or not there was a
178 2 dgisselq
framing error (i.e., no stop bit), and {\tt o\_parity\_err} will indicate
179 5 dgisselq
whether or not the parity matched.  Finally, the {\tt o\_break} line will
180
indicate whether the receiver is in a ``break'' state,
181 2 dgisselq
 
182
The {\tt tx\_busy} line may be inverted and connected to a transmit interrupt
183
line.  In a similar fashion, the {\tt rx\_stb} line, or the bus equivalent of
184 5 dgisselq
{\tt rx\_ready}, may be used for receive interrupt lines--although it will need
185
to be latched as both {\tt wbuart.v} and {\tt wbuart-insert.v} demonstrate.
186 2 dgisselq
 
187 5 dgisselq
An simple example of how to put this configuration together is found in
188 2 dgisselq
{\tt wbuart-insert.v}.  In this example given, the {\tt rx\_data} register
189
will have only the lower eight bits set if the data is valid, higher bits will
190
be set upon error conditions, and cleared automatically upon the next byte read.
191
In a similar fashion, the {\tt tx\_data} register can be written to with a byte
192 12 dgisselq
in order to transmit that byte.  Writing bit ten will place the transmitter
193
into a ``break'' condition, which will only be cleared by writing a zero to
194
that bit later.
195 2 dgisselq
Reading from the {\tt tx\_data} register can also be used to determine if the
196
transmitter is busy (via polling), whether it is currently in a break condition,
197
or even what bit is currently being placed to the output port.
198
 
199 5 dgisselq
A more comprehensive example of how these UART modules may be used together
200
can be found in {\tt wbuart.v}.  This file provides a full wishbone interface
201
allowing interaction with the core using four registers: a setup register,
202
receive register and transmit register as before, as well as a FIFO health
203
register through which the size and fill of the FIFO can be queried.
204
 
205 2 dgisselq
The C++ simulation portion of the code revolves around the file
206
{\tt bench/cpp/uartsim.cpp} and its associated header.  This file defines a
207
class, {\tt UARTSIM}, which can be used to connect the UART to a TCP/IP stream.
208
When initialized, this class takes, as input, the TCP/IP port number that the
209 5 dgisselq
class is to connect with.  Setting the port to zero connects the UART to
210
the standard input and output file facilities.  Once connected, using this
211
simulator is as simple as calculating the receive input bit from the transmit
212
output bit when the clock is low, and the core takes care of everything else.
213 2 dgisselq
 
214 5 dgisselq
Finally, there are a series of example files found in the bench/verilog
215
directory.  {\tt helloworld.v} presents an example of a simple UART transmitter
216 6 dgisselq
sending the ``Hello, World {\textbackslash}r{\textbackslash}n'' message over
217
and over again.  This example
218 5 dgisselq
uses only the {\tt txuart.v} module, and can be simulated in Verilator.
219 12 dgisselq
A second test file, {\tt echotest.v}, works by echoing every received character
220
to the transmit port.
221
This tests both {\tt txuart.v} and {\tt rxuart.v}.
222
A third test file, {\tt linetest.v}, works by waiting for a line of data to be
223
received, after which it parrots that line back to the terminal.
224
A fourth test file, {\tt speechfifo.v} tests both the wishbone interface as
225
well as the FIFO, by filling the UART, 10~samples at a time, with text from
226
Abraham Lincoln's Gettysburg address.
227
All three of these example files may be used as stand-alone top--level design
228
files to verify your own UART hardware functionality.
229 5 dgisselq
 
230 2 dgisselq
\chapter{Operation}\label{ch:ops}
231
 
232
% This section describes the operation of the core.  Specific sequences, such
233
% as startup sequences, as well as the modes and states of the block should be
234
% described.
235
%
236
 
237 12 dgisselq
To use the core, a couple of steps are required.  First, wire it up.  This
238
includes wiring the {\tt i\_uart} and {\tt o\_uart} ports, as well as any
239 15 dgisselq
{\tt i\_cts\_n} and/or {\tt o\_rts\_n} hardware flow control.  The
240 5 dgisselq
{\tt rxuart.v} and {\tt txuart.v} files may be wired up for use individually,
241 12 dgisselq
or as part of a large module such as the example in{\tt wbuart-insert.v}.
242
Alternatively, the {\tt wbuart.v} file may be connected to a straight 32--bit
243
wishbone bus.
244 5 dgisselq
Second, set the UART configuration register.  This is ideally set by setting
245
the {\tt INITIAL\_SETUP} parameter of {\tt rxuart}, {\tt txuart} or even
246 12 dgisselq
{\tt wbuart}  Alternatively, you can write to the setup register at a later
247
time, as is done within the {\tt speechfifo.v} bench test.
248 2 dgisselq
 
249 12 dgisselq
From a simulation standpoint, it will also need to be ``wired'' up inside your
250 5 dgisselq
C++ main Verilator file.  Somewhere, internal to the top--level Verilator
251
C++ simulation file, you'll want to have some setup lines similar to,
252 2 dgisselq
\begin{tabbing}
253 5 dgisselq
\hbox to 3.0in{\tt \#include "uartsim.h"} \= {\em // Tell compiler about UARTSIM}\\
254
\vdots \\
255
{\tt UARTSIM *uartsim;} \> {\em // Declare a variable to hold the simulator}\\
256
{\tt uartsim = new UARTSIM(ip\_port);} \> {\em // Create/initialize it with your TCP/IP port \#} \\
257
{\tt uartsim->setup(setup\_register\_value);} \> {\em // Tell it the line coding to expect}\\
258
\end{tabbing}
259
and then another set of lines within your clocked section that look something
260
like,
261
\begin{tabbing}
262 2 dgisselq
{\tt if (!clk)} \= \\
263 5 dgisselq
\> {\tt tb->i\_uart\_rx} {\tt = } {\tt uartsim(tb->o\_uart\_tx);}
264 2 dgisselq
\end{tabbing}
265 5 dgisselq
You should be able to find several examples of this in the {\tt helloworld.cpp},
266
{\tt linetest.cpp}, and {\tt speechtest.cpp} files.  These C++ implementations,
267
though, are also complicated by the need for a self--contained testing program
268
to be able to capture and know what was placed onto the standard input and
269
output streams, hence many of them fork() into two processes so that one
270
process can verify the output of the other.  Both {\tt speechtest.cpp} and
271
{\tt linetest.cpp} allow a {\em -i} option to run in an interactive mode without
272
forking.  Either way, forking the simulation program shouldn't be needed for
273
normal usages of these techniques, but you may find it helpful to know should
274
you examine this code or should you wish to build your own test file that
275
proves its own output.
276 2 dgisselq
 
277
To use the transmitter, set the {\tt i\_stb} and {\tt i\_data} wires.  Drop
278
the strobe line any time after {\tt (i\_stb)\&\&(!o\_busy)}.
279
 
280
To use the receiver, grab the data any time {\tt o\_stb} is true.
281
 
282
From the standpoint of the bus, there are two ways to handle receiving and
283
transmitting: polling and interrupt based, although both work one character at
284 5 dgisselq
a time.  To poll, repeatedly read the receive data register until only bits from
285
the bottom eight are set.  This is an indication that the byte is
286 2 dgisselq
valid.  Alternatively, you could wait until the an interrupt line is set and
287 5 dgisselq
then read.  In the {\tt wbuart-insert.v} example as well as the {\tt wbuart.v}
288
implementation, the {\tt o\_uart\_rx\_int} line will be set ({\tt rx\_int} for
289
{\tt wbuart-insert.v}), and automatically cleared upon any read.  To write,
290
one can read from the transmit data register until the eighth bit, the
291
{\tt tx\_busy} bit, is cleared, and then transmit.  Alternatively, this
292
negation of this bit may be connected to an interrupt line,
293
{\tt o\_uart\_tx\_int}.  Writing to the port while the transmitter is idle will
294
start it transmitting.  Writing to the port while it is busy will fill a one
295
word buffer that will get sent as soon as the port is idle for one clock.
296 2 dgisselq
 
297
 
298
\chapter{Registers}\label{ch:registers}
299
% This section specifies all internal registers.  It should completely cover
300
% the interface between the CPU and the host as seen from the software point
301
% of view.
302
 
303
% List of Registers
304
 
305
% Register 1 Description
306
%
307
% You shall choose the style of register you prefer.  Do not use both options
308
% in one and the same document.  (Table of bits, vs. byetarray type of
309
% description).
310
 
311 5 dgisselq
The {\tt wbuart} core supports four registers, shown in Tbl.~\ref{tbl:reglist}.
312
\begin{table}\begin{center}\begin{reglist}
313
{\tt SETUP}   & 2'b00 & 30 & R/W & UART configuration/setup register.\\\hline
314
{\tt FIFO}    & 2'b01 & 32 & R & Returns size and status of the FIFOs\\\hline
315
{\tt RX\_DATA}& 2'b10 & 13 & R & Read data, reads from the UART.\\\hline
316
{\tt TX\_DATA}& 2'b11 & 15 & (R/)W & Transmit data: writes send out the UART.
317
                \\\hline
318 2 dgisselq
\end{reglist}\caption{UART Registers}\label{tbl:reglist}
319
\end{center}\end{table}
320 5 dgisselq
We'll cover the format of all of these registers here, as they are defined by
321
{\tt wbuart.v}.
322 2 dgisselq
 
323
\section{Setup Register}
324
The setup register is perhaps the most critical of all the registers.  This
325
is shown in Fig.\ref{fig:SETUP}.
326
\begin{figure}\begin{center}
327
\begin{bytefield}[endianness=big]{32}
328
\bitheader{0-31}\\
329 12 dgisselq
\bitbox{1}{0}
330
\bitbox{1}{H}
331 2 dgisselq
\bitbox{2}{N}
332
\bitbox{1}{S}
333
\bitbox{1}{P}
334
\bitbox{1}{F}
335
\bitbox{1}{T}
336
\bitbox{24}{Baud CLKS}
337
\end{bytefield}
338
\caption{SETUP Register fields}\label{fig:SETUP}
339
\end{center}\end{figure}
340
It is designed so that, for any 8N1 protocol (eight data bits, no parity, one
341 12 dgisselq
stop bit, hardware flow control on), all of the upper bits will be set to zero
342
so that only the number of
343
clocks per baud interval needs to be set.
344
The top bit is unused, making this a 31--bit number.
345
The other fields are: $H$ which, when set, turns off any hardware flow
346
control.  $N$ sets the number of bits per word.  A value of zero
347 5 dgisselq
corresponds to 8--bit words, a value of one to seven bit words, and so forth up
348
to a value of three for five bit words.  $S$ determines the number of stop
349
bits.  Set this to one for two stop bits, or leave it at zero for a single
350
stop bit.  $P$ determines whether or not a parity bit is used (1~for parity,
351
0~for no parity), while $F$ determines whether or not the parity is fixed.
352
Tbl.~\ref{tbl:parity} lists out the various values possible here.
353 2 dgisselq
\begin{table}\begin{center}
354
\begin{tabular}{ccc|l}
355
P&F&T&Setting \\\hline\hline
356
1 & 0 & 0 & Odd parity          \\\hline
357
1 & 0 & 1 & Even parity \\\hline
358
1 & 1 & 0 & Parity bit is a Space (1'b0)\\\hline
359
1 & 1 & 1 & Parity bit is a Mark (1'b1)\\\hline
360
 
361
\end{tabular}\caption{Parity setup}\label{tbl:parity}
362
\end{center}\end{table}
363
 
364 6 dgisselq
The final portion of this register is the baud {\tt CLKS}.  This is the number
365 12 dgisselq
of ticks of your system clock per baud interval,
366 6 dgisselq
\begin{eqnarray*}
367
{\tt CLKS} &=& \frac{f_{\mbox{\tiny SYS}}}{f_{\mbox{\tiny BAUD}}}.
368
\end{eqnarray*}
369
Rounding to the nearest integer is recommended.  Hence, if you have a system
370
clock of 100~MHz and wish to achieve 115,200~Baud, you would set {\tt CLKS} to
371
\begin{eqnarray*}
372
{\tt CLKS}_{\tiny{\tt Example}} &=& \frac{100 \cdot 10^6}{115200}
373
        \frac{\mbox{Clocks per Second}}{\mbox{Baud Intervals per Second}}
374
        \approx 868 \mbox{ Clocks per Baud Interval}
375
\end{eqnarray*}
376
 
377 5 dgisselq
Changes to this setup register will take place in the transmitter as soon as
378
the transmitter is idle and ready to accept another byte.
379
 
380
Changes to this setup register in {\tt rxuart.v} also take place between bytes.
381
However, within the {\tt wbuart.v} context, any changes to the setup register
382
will also reset the receiver and receive FIFO together.  Once reset, the
383
receiver will insist on a minimum of sixteen idle baud intervals before
384
receiving the next byte.
385
 
386
\section{FIFO Register}
387
The FIFO register is a read--only register containing information about the
388
status of both receive and transmit FIFOs within it.  The transmit FIFO
389
information is kept in the upper 16--bits, and the receiver FIFO information
390
in the lower 1-bits, as shown in Fig.~\ref{fig:FIFO}.
391
\begin{figure}\begin{center}
392
\begin{bytefield}[endianness=big]{32}
393
\bitheader{0-31}\\
394
\bitbox[rlt]{4}{LGLN}
395
\bitbox[rlt]{10}{TX Fill}
396
\bitbox[rlt]{1}{H}
397
\bitbox[rlt]{1}{Z}
398
\bitbox[rlt]{4}{}
399
\bitbox[rlt]{10}{}
400
\bitbox[rlt]{1}{}
401
\bitbox[rlt]{1}{} \\
402
\bitbox[rlb]{4}{}
403
\bitbox[rlb]{10}{}
404
\bitbox[rlb]{1}{}
405
\bitbox[rlb]{1}{}
406
\bitbox[rlb]{4}{LGLN}
407
\bitbox[rlb]{10}{RX Fill}
408
\bitbox[rlb]{1}{H}
409
\bitbox[rlb]{1}{Z} \\
410
\end{bytefield}
411
\caption{RXDATA Register fields}\label{fig:FIFO}
412
\end{center}\end{figure}
413
We'll discuss each of these bits individually.
414
 
415
The {\tt LGLN} field indicates the log base two of the FIFO length.  Hence an
416
{\tt LGLN} field of four would indicate a FIFO length of sixteen values.
417 12 dgisselq
The FIFO fill for the transmitter indicates the number of available spaces
418
within the transmit FIFO, while the FIFO fill in the receiver indicates the
419
current number of spaces within the FIFO having valid data.  The $H$ bit will
420
be true if the high order FIFO fill bit is set.
421
Finally, the $Z$ bit will be true for the transmitter if there is at least one
422
open space in the FIFO, and true in the receiver if there is at least one value
423
needing to be read.
424 5 dgisselq
 
425
The $H$ and $Z$ bits also mirror the interrupt bits generated by {\tt wbuart.v}.
426
Interrupts will be generated any time the FIFO is half full (on receive), or
427 12 dgisselq
less than half full (on transmit). The same logic applies for the $Z$ bit.  An
428
interrupt will be generated any time the FIFO in non-empty (on receive), or
429
not full (on transmit).
430 5 dgisselq
 
431 12 dgisselq
Writes to this FIFO status register are quietly ignored.
432 5 dgisselq
 
433 2 dgisselq
\section{RX\_DATA Register}
434
Fig.~\ref{fig:RXDATA}
435
\begin{figure}\begin{center}
436
\begin{bytefield}[endianness=big]{32}
437
\bitheader{0-31}\\
438 5 dgisselq
\bitbox[rlt]{19}{19'h00}
439
\bitbox{1}{E}
440
\bitbox[rlt]{1}{B}
441
\bitbox[rlt]{1}{F}
442
\bitbox[rlt]{1}{P}
443
\bitbox[rlt]{1}{S}
444
\bitbox[rlt]{8}{RWORD} \\
445
\bitbox[lrb]{19}{}
446
\bitbox{1}{-}
447
\bitbox[lrb]{1}{}
448
\bitbox[lrb]{1}{}
449
\bitbox[lrb]{1}{}
450
\bitbox[lrb]{1}{}
451
\bitbox[lrb]{8}{}
452 2 dgisselq
\end{bytefield}
453
\caption{RXDATA Register fields}\label{fig:RXDATA}
454
\end{center}\end{figure}
455
breaks out the various bit fields of the receive
456 5 dgisselq
data register used in {\tt wbuart.v}.  In particular, the $B$ field indicates
457
that the receive line is in a break condition.  The $F$ and $P$ fields indicate
458
that a frame error or parity error has been detected.  These bits are not self
459
clearing, but rather are cleared by writing to 1's to them.  The $S$ field will
460
be false when the {\tt RWORD} is valid.  Hence, if {\tt (RWORD \& ~0x0ff)} is
461
zero there is a word ready to be received without error.
462 2 dgisselq
 
463 5 dgisselq
The $E$ bit is an error bit.  When set, it indicates that the FIFO has
464
overflowed sometime since the last reset.  This bit is also a reset bit.
465 12 dgisselq
In other words, writing a {\tt 1'b1} to this bit will command a receive
466 5 dgisselq
reset: clearing the FIFO, and waiting for the line to be idle before receiving
467
another byte.  This bit is not implemented in {\tt wbuart-insert.v}, but
468
exists in the {\tt wbuart.v} implementation.
469
 
470 2 dgisselq
\section{TX\_DATA Register}
471
Fig.~\ref{fig:TXDATA}
472
\begin{figure}\begin{center}
473
\begin{bytefield}[endianness=big]{32}
474
\bitheader{0-31}\\
475 12 dgisselq
\bitbox[lrt]{16}{16'h00}
476
\bitbox{1}{R}
477 5 dgisselq
\bitbox{1}{H}
478
\bitbox{1}{Z}
479
\bitbox{1}{E}
480
\bitbox[lrt]{1}{C}
481
\bitbox[lrt]{1}{O}
482
\bitbox[lrt]{1}{B}
483
\bitbox[lrt]{1}{S}
484
\bitbox[lrt]{8}{TWORD} \\
485
\bitbox[lrb]{17}{}
486
\bitbox{3}{3'h0}
487
\bitbox[lrb]{1}{}
488
\bitbox[lrb]{1}{}
489
\bitbox[lrb]{1}{}
490
\bitbox[lrb]{1}{}
491
\bitbox[lrb]{8}{}
492 2 dgisselq
\end{bytefield}
493
\caption{TXDATA Register fields}\label{fig:TXDATA}
494
\end{center}\end{figure}
495
breaks out the various bit fields of the transmit data register used in
496 5 dgisselq
{\tt wbuart.v}.  The $C$ field indicates whether or not the receive
497 2 dgisselq
data line is high or low, the $O$ field indicates the same for the transmit
498 5 dgisselq
line.  These aren't particularly useful or valuable, but the $C$ bit doesn't
499
fit in the receive data register since it would violate the error condition
500
detector.  These two bits are thrown in here for whatever useful purpose one
501 12 dgisselq
might find.  The $B$ field, when set, transmits a break condition.
502 5 dgisselq
Further, writes to the TXDATA register while in a break condition and with the
503
$B$ field clear, will clear the transmitter from any break condition without
504
transmitting anything.  The $S$ field is similar to the RXDATA strobe register.
505
It is a read--only bit that will be true any time the transmitter is busy.
506 12 dgisselq
It will be clear only when the transmitter is idle.
507
Finally, the upper $R$ bit at the top of the register is the instantaneous
508
value of the received ready-to-send (RTS) value.
509 2 dgisselq
 
510 5 dgisselq
The final three bits, $H$, $Z$, and $E$, are present only in {\tt wbuart.v}.
511
These bits indicate $H$ if the FIFO is at least half full, $Z$ if the FIFO is
512 12 dgisselq
not full, and $E$ if the FIFO has experienced an overflow condition since the
513 5 dgisselq
last reset. Writing a {\tt 1'b1} to the $E$ bit will reset the transmit FIFO,
514
both clearing any error indication in the FIFO as well as clearing the FIFO
515
itself.
516 2 dgisselq
 
517 5 dgisselq
To use the transmitter, simply write a byte to the TXDATA register
518
with the upper 24--bits clear to transmit.
519
 
520 2 dgisselq
\chapter{Clocks}\label{ch:clocks}
521
The UART has been tested with a clock as fast as 200~MHz
522
(Tbl.~\ref{tbl:clocks}).
523
\begin{table}\begin{center}
524
\begin{clocklist}
525
{\tt i\_clk} & (System) & 200~MHz & & System clock\\\hline
526
\end{clocklist}
527
\caption{Clock Requirements}\label{tbl:clocks}
528
\end{center}\end{table}
529
It should be able to use slower clocks, but only subject to the ability to
530
properly set the baud rate as shown in Eqn.~\eqref{eqn:baudlimit} on
531
Page~\pageref{eqn:baudlimit}.
532
 
533
I do not recommend using this core with a baud rate greater than a quarter
534
of the system clock rate.
535
 
536
% This section specifies all of the clocks.  All clocks, clock domain passes
537
% and the clock relations should be described.
538
 
539
% Name | Source |    Rates (MHz)    | Remarks | Description
540
%               | Max|Min|Resolution|
541
\chapter{Wishbone Datasheet}\label{ch:wishbone}
542
 
543
Tbl.~\ref{tbl:wishbone}
544 5 dgisselq
\begin{table}[htbp]\begin{center}\begin{tabular}{|p{2.5in}|p{3.5in}|}\hline
545
\rowcolor[gray]{0.85} Description & Specification \\\hline\hline
546 2 dgisselq
Revision level of wishbone & WB B4 spec \\\hline
547
Type of interface & Slave, Read/Write, pipeline reads supported \\\hline
548
Port size & 32--bit \\\hline
549
Port granularity & 32--bit \\\hline
550
Maximum Operand Size & 32--bit \\\hline
551
Data transfer ordering & (Irrelevant) \\\hline
552
Clock constraints & None.\\\hline
553 5 dgisselq
Signal Names & \begin{tabular}{lll}
554
                {\tt wbuart.v} & {\tt wbuart-insert.v} & WB Equivalent \\\hline
555
                {\tt i\_clk} & {\tt i\_wb\_clk} & {\tt CLK\_I} \\
556
                {\tt i\_rst} & & {\tt RST\_I} \\
557
                {\tt i\_wb\_cyc}   & {\tt i\_wb\_cyc} & {\tt CYC\_I} \\
558
                {\tt i\_wb\_stb}   & {\tt i\_wb\_stb} & {\tt STB\_I} \\
559
                {\tt i\_wb\_we}    & {\tt i\_wb\_we} & {\tt WE\_I} \\
560
                {\tt i\_wb\_addr}  & {\tt i\_wb\_addr} & {\tt ADR\_I} \\
561
                {\tt i\_wb\_data}  & {\tt i\_wb\_data} & {\tt DAT\_I} \\
562
                {\tt o\_wb\_ack}   & {\tt o\_wb\_ack} & {\tt ACK\_O} \\
563
                {\tt o\_wb\_stall} & {\tt o\_wb\_stall} & {\tt STALL\_O} \\
564
                {\tt o\_wb\_data}  & {\tt o\_wb\_data} & {\tt DAT\_O}
565 2 dgisselq
                \end{tabular}\\\hline
566 5 dgisselq
\end{tabular}
567 2 dgisselq
\caption{Wishbone Datasheet}\label{tbl:wishbone}
568
\end{center}\end{table}
569
is required by the wishbone specification in order to declare the core as
570
wishbone compliant, and so it is included here.  It references the connections
571 5 dgisselq
used in {\tt wbuart.v} as well as those exemplified by {\tt wbuart-insert.v}.
572
The big thing to notice is that this core acts as a wishbone slave, and that
573
all accesses to the core registers are 32--bit reads and writes to this
574 12 dgisselq
interface---not the 8--bit reads or writes that might be expected from any
575
other 8'bit serial interface.
576 2 dgisselq
 
577
What this table doesn't show is that all accesses to the port take a single
578 5 dgisselq
clock for {\tt wbuart-insert.v}, or two clocks for {\tt wbuart.v}.  That is, if
579
the {\tt i\_wb\_stb} line is high on one clock, the {\tt i\_wb\_ack} line will
580
be high the next for single clock access, or the clock after that for two
581
clock access.  Further, the {\tt o\_wb\_stall} line is tied to zero.
582 2 dgisselq
 
583
Also, this particular wishbone implementation assumes that if {\tt i\_wb\_stb},
584
then {\tt i\_wb\_cyc} will be high as well.  Hence it only checks whether or not
585
{\tt i\_wb\_stb} is true to determine if a transaction has taken place.  If your
586
bus does not meet this requirement, you'll need to AND {\tt i\_wb\_stb} with
587
{\tt i\_wb\_cyc} before using the core.
588
 
589
\chapter{I/O Ports}\label{ch:ioports}
590
% This section specifies all of the core IO ports
591
 
592 5 dgisselq
In it's simplest form, the UART offers simply two I/O ports: the
593
{\tt i\_uart\_rx} line to receive, and the {\tt o\_uart\_tx} line to transmit.
594
These lines need to be brought to the outside of your design.  Within
595
Verilator, they need to be connected inside your Verilator test bench, as in:
596 2 dgisselq
\begin{tabbing}
597
{\tt if (!clk)} \= \\
598 5 dgisselq
\> {\tt tb->i\_uart\_rx} {\tt = } {\tt uartsim(tb->o\_uart\_tx);}
599 2 dgisselq
\end{tabbing}
600
 
601 12 dgisselq
For those interested in hardware flow control, the core also offers an
602 15 dgisselq
{\tt i\_cts\_n} input to control the flow out of our transmitter, and an
603
{\tt o\_rts\_n} output to indicate when the receiver is full.  Both of these
604
wires are active low.
605 12 dgisselq
 
606 15 dgisselq
For those not interested in flow control there are three
607
possibilities.  First, one can set the module parameter
608
{\tt HARDWARE\_FLOW\_CONTROL\_PRESENT} to zero which will disable hardware
609
flow control.  This will also permanently set the hardware flow control is off
610
bit in the setup register.  Second, hardware flow control can be disabled by
611
connecting a {\tt 1'b0} wire to {\tt i\_cts\_n} and by ignoring the
612
{\tt o\_rts\_n} output.  In this case, the hardware flow control setup bit
613
becomes an unused flip flop within the driver. The third way to disable
614
hardware flow control is to simply disable it within the setup register.  In
615
general, these approaches will only affect the transmitter's operation and how
616
the {\tt o\_rts\_n} bit gets set.
617
 
618 2 dgisselq
A more detailed discussion of the connections associated with these modules
619 5 dgisselq
can begin with Tbl.~\ref{tbl:rxports},
620 2 dgisselq
\begin{table}\begin{center}\begin{portlist}
621
{\tt i\_clk}    & 1 & Input & The system clock \\\hline
622
{\tt i\_reset}  & 1 & Input & A positive, synchronous reset \\\hline
623 12 dgisselq
{\tt i\_setup}  & 31 & Input & The 31--bit setup register \\\hline
624 2 dgisselq
{\tt i\_uart}   & 1 & Input & The input wire from the outside world. \\\hline
625
{\tt o\_wr}     & 1 & Output & True if a word was received.  At this time,
626
                {\tt o\_data}, {\tt o\_break}, {\tt o\_parity\_err}, and
627
                {\tt o\_frame\_err} will also be valid. \\\hline
628
{\tt o\_data}   & 8 & Output & The received data, valid if {\tt o\_wr} \\\hline
629
{\tt o\_break}  & 1 & Output & True in the case of a break condition \\\hline
630
{\tt o\_parity\_err}    & 1 & Output & True if a parity error was detected \\\hline
631
{\tt o\_frame\_err}     & 1 & Output & True if a frame error was detected \\\hline
632
{\tt o\_ck\_uart}       & 1 & Output & A synchronized copy of {\tt i\_uart} \\\hline
633
\end{portlist}\caption{RXUART port list}\label{tbl:rxports}
634
\end{center}\end{table}
635 5 dgisselq
detailing the I/O ports of the UART receiver, Tbl.~\ref{tbl:txports},
636 2 dgisselq
\begin{table}\begin{center}\begin{portlist}
637
{\tt i\_clk}    & 1 & Input & The system clock \\\hline
638
{\tt i\_reset}  & 1 & Input & A positive, synchronous reset \\\hline
639 12 dgisselq
{\tt i\_setup}  & 31 & Input & The 31--bit setup register \\\hline
640 2 dgisselq
{\tt i\_break}  & 1 & Input & Set to true to place the transmit channel into a break condition\\\hline
641
{\tt i\_wr}     & 1 & Input & An input strobe.  Set to one when you wish to transmit data, clear once it has been accepted\\\hline
642
{\tt i\_data}   & 8 & Input & The data to be transmitted, ignored unless
643
                {\tt (i\_wr)\&\&(!o\_busy)} \\\hline
644 15 dgisselq
{\tt i\_cts\_n} & 1 & Input & A hardware flow control wire, true if the transmitter is cleared to send, active low\\\hline
645 2 dgisselq
{\tt o\_uart}   & 1 & Output & The wire to be connected to the external port\\\hline
646
{\tt o\_busy}   & 1 & Output & True if the transmitter is busy, false if it will receive data\\\hline
647
\end{portlist}\caption{TXUART port list}\label{tbl:txports}
648
\end{center}\end{table}
649 5 dgisselq
detailing the I/O ports of the UART transmitter, and Tbl.~\ref{tbl:wbports}
650
\begin{table}\begin{center}\begin{tabular}{|p{1.15in}|p{0.1in}|p{0.75in}|p{3.375in}|}
651
\rowcolor[gray]{0.85} Port & W & Direction & Description \\\hline\hline
652
{\tt i\_uart\_rx}& 1 & Input & The receive wire coming from the external port\\\hline
653
{\tt o\_uart\_tx}& 1 & Output & The transmit wire to be connected to the external port\\\hline
654 15 dgisselq
{\tt i\_cts\_n}& 1 & Input  & The hardware flow control {\tt clear-to-send} input for the transmitter, active low\\\hline
655
{\tt o\_rts\_n}& 1 & Output & The hardware flow control {\tt ready-to-send} (receive) output, also active low\\\hline
656 5 dgisselq
{\tt o\_uart\_rx\_int}  & 1 & Output & True if a byte may be read from the receiver\\\hline
657 12 dgisselq
{\tt o\_uart\_tx\_int}  & 1 & Output & True if a byte may be sent to the transmitter\\\hline
658 5 dgisselq
{\tt o\_uart\_rxfifo\_int}&1& Output & True if the receive FIFO is half full\\\hline
659
{\tt o\_uart\_txfifo\_int}&1& Output & True if the transmit FIFO is half empty\\\hline
660
\end{tabular}\caption{WBUART port list}\label{tbl:wbports}
661
\end{center}\end{table}
662
detailing the non--wishbone I/O ports of the wishbone controller.
663 2 dgisselq
 
664
% Appendices
665
% A. May be added to outline different specifications.  (??)
666
 
667
 
668
% Index
669
\end{document}
670
 
671
 

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.