b283c82665c4ab9f0c4451966347fd8b6093bc51
[mw/milkymist.git] / doc / system.tex
1 \documentclass[a4paper,11pt]{article}
2 \usepackage{fullpage}
3 \usepackage[latin1]{inputenc}
4 \usepackage[T1]{fontenc}
5 \usepackage[normalem]{ulem}
6 \usepackage[english]{babel}
7 \usepackage{listings,babel}
8 \lstset{breaklines=true,basicstyle=\ttfamily}
9 \usepackage{graphicx}
10 \usepackage{moreverb}
11 \usepackage{float}
12 \usepackage{url}
13 \usepackage{tabularx}
14
15 \title{Milkymist system reference manual}
16 \author{S\'ebastien Bourdeauducq}
17 \date{November 2009}
18 \begin{document}
19 \maketitle{}
20 \section{What is Milkymist}
21 The goal of the project is to develop a small stand-alone board that is capable of rendering MilkDrop presets in real time from an audio input (analog or digital), and displaying them on a VGA screen.
22
23 Open source components have been used as much as possible, and therefore a system-on-chip implemented in a FPGA has been chosen for meeting this goal as well as simplifying the PCB. Only a few components need to be added for a minimal video synthesis board:
24 \begin{itemize}
25 \item Off-chip memory
26 \item VGA DAC
27 \item Microphone and audio ADC
28 \item Debug console
29 \end{itemize}
30
31 \section{Supported boards}
32 \subsection{Milkymist One}
33
34 \subsection{Xilinx ML401 development board}
35 This board is equipped with a Virtex-4 FPGA (XC4VLX25). Milkymist can use the on-board peripherals of the ML401:
36 \begin{itemize}
37 \item VGA output (Analog Devices ADV7125KST50 3x8-bit D/A converter)
38 \item AC'97 audio codec (National Semiconductor LM4550)
39 \item CF card slot (through Xilinx SystemACE)
40 \item RS232 port
41 \item LCD screen (Lumex LCM-S01602DTR/M, HD44780-compatible)
42 \item LEDs
43 \item PS/2
44 \item Buttons
45 \item Parallel flash
46 \item DDRAM (two Infineon HYB25D256160BT-7 chips)
47 \end{itemize}
48
49 \subsection{Avnet Spartan-3A evaluation kit}
50 This board is equipped with a Spartan-3A XC3S400A chip. Because of the limited FPGA capacity and the small number of on-board peripherals, support for this board is only for educational and evaluation purposes.
51
52 The following peripherals are supported:
53 \begin{itemize}
54 \item RS232 port
55 \item LEDs
56 \item Buttons
57 \item Parallel flash
58 \end{itemize}
59
60 \section{Components and bus architecture}
61
62 \begin{figure}[H]
63 \centering
64 \includegraphics[height=170mm]{soc_architecture.eps}
65 \caption{SoC block diagram}
66 \end{figure}
67
68 \subsection{Softcore CPU}
69 The system is equipped with a small general-purpose CPU that drives the hardware acceleration units and performs software-friendly tasks such as GUI and filesystem handling.
70
71 Mico32 from Lattice Semiconductor has been chosen for this purpose. It can run a special MMU-less version of Linux, and the Milkymist BIOS supports direct loading and booting of Linux kernels.
72
73 \subsection{System memory}
74 \subsubsection{NOR flash}
75 The Milkymist BIOS is stored in an external NOR flash chip. The NOR flash controller in Milkymist has been designed to prioritize hardware simplicity over performance and functionality. It only supports reading from the flash; storing the boot image must be done using another tool.
76
77 \subsubsection{On-chip SRAM}
78 The SoC is equipped with a 4KB on-chip RAM, which is mainly used for the initial execution environment, before SDRAM is initialized and functional.
79
80 The choice has been made to include this on-chip RAM so that advanced debug programs that do not rely on SDRAM can easily be developed and run. Those programs are very useful for debugging the SDRAM, which is often prone to problems.
81
82 \subsubsection{SDRAM}
83 For large volatile data storage, Milkymist is designed to use affordable and industry-standard DDR SDRAM chips. A custom memory controller (HPDMC) has been designed as part of the project, as all other free cores were either non-functional or slow.
84
85 The memory controller implements the proprietary high-performance FML bus to deliver low-latency and high-bandwidth memory access while using few FPGA resources. FML has been designed as part of the Milkymist project.
86
87 \subsection{UART}
88 A simple UART is included, intended to implement a debug console. The UART parameters are fixed: 115200 bps, 8 bits per character, no parity, 1 stop bit.
89
90 \subsection{System controller}
91 The design uses a ``system controller'' core which includes the interrupt controller, GPIO, two timers, and a 32-bit identification number for the board.
92
93 See the ``GPIO maps'' and ``IRQ maps'' sections for GPIO and IRQ assignments.
94
95 \subsection{Memory card}
96 On the ML401, the CF card is accessed through the Xilinx SystemACE chip. The registers of this chip are mapped in the softcore CPU address space using the WISHBONE bus.
97
98 \subsection{VGA controller}
99 Milkymist uses a VGA signal generator which reads from a RGB565 framebuffer, and implements an FML master to fetch data from the memory. The VGA generator is controlled using a CSR interface.
100
101 \subsection{Audio}
102 Milkymist can record and play audio through an AC'97 codec. The core that drives the codec is controlled via a CSR interface and supports DMA reads and writes of the PCM data over Wishbone.
103
104 \subsection{Programmable Floating Point Unit (PFPU)}
105 The PFPU is a simple and high-speed floating point microprocessor, designed to do the bulk vertex data generation for each frame in little time.
106
107 It has a WISHBONE master for writing the output buffer, and a CSR interface for control.
108
109 \subsection{Texture Mapping Unit (TMU)}
110 The engine performs texture mapping on a triangle strip. It is a central component of MilkDrop acceleration.
111
112 It has two FML master interfaces for fetching pixel data, a WISHBONE master to fetch the vertex data, and a CSR slave for control.
113
114 \subsection{PS/2 controller}
115 Milkymist supports standard PS/2 keyboard/mouse port in read-only mode. This is only implemented on the ML401 board.
116
117 \section{GPIO map}
118
119 \subsubsection{Inputs}
120
121 \begin{tabularx}{\textwidth}{|l|l|X|}
122 \hline
123 \bf{PIO bit} & \bf{Direction} & \bf{Description} \\
124 \hline
125 0 & Input & Pushbutton North (ML401 only) \\
126 \hline
127 1 & Input & Pushbutton West \\
128 \hline
129 2 & Input & Pushbutton South (ML401 only) \\
130 \hline
131 3 & Input & Pushbutton East \\
132 \hline
133 4 & Input & Pushbutton Center \\
134 \hline
135 5 & Input & DIP switch 1 \\
136 \hline
137 6 & Input & DIP switch 2 \\
138 \hline
139 7 & Input & DIP switch 3 \\
140 \hline
141 8 & Input & DIP switch 4 \\
142 \hline
143 9 & Input & DIP switch 5 (ML401 only) \\
144 \hline
145 10 & Input & DIP switch 6 (ML401 only) \\
146 \hline
147 11 & Input & DIP switch 7 (ML401 only) \\
148 \hline
149 12 & Input & DIP switch 8 (ML401 only) \\
150 \hline
151 \end{tabularx}
152
153 \subsubsection{Outputs}
154
155 \begin{tabularx}{\textwidth}{|l|l|X|}
156 \hline
157 \bf{PIO bit} & \bf{Direction} & \bf{Description} \\
158 \hline
159 0 & Output & LED 2 (NB. ML401's LED 0 and LED 1 respectively monitor UART transmission and reception) \\
160 \hline
161 1 & Output & LED 3 \\
162 \hline
163 2 & Output & LED North (ML401 only) \\
164 \hline
165 3 & Output & LED West (ML401 only) \\
166 \hline
167 4 & Output & LED South (ML401 only) \\
168 \hline
169 5 & Output & LED East (ML401 only) \\
170 \hline
171 6 & Output & LED Center (ML401 only) \\
172 \hline
173 7 & Output & HD44780-compatible LCD (ML401 only) -- E pin \\
174 \hline
175 8 & Output & HD44780-compatible LCD (ML401 only) -- RS pin \\
176 \hline
177 9 & Output & HD44780-compatible LCD (ML401 only) -- RW pin \\
178 \hline
179 10 & Output & HD44780-compatible LCD (ML401 only) -- D4 pin \\
180 \hline
181 11 & Output & HD44780-compatible LCD (ML401 only) -- D5 pin \\
182 \hline
183 12 & Output & HD44780-compatible LCD (ML401 only) -- D6 pin \\
184 \hline
185 13 & Output & HD44780-compatible LCD (ML401 only) -- D7 pin \\
186 \hline
187 \end{tabularx}
188
189 \section{Address map}
190
191 \begin{tabularx}{\textwidth}{|l|l|X|}
192 \hline
193 \bf{Base address} & \bf{Cacheable} & \bf{Peripheral} \\
194 \hline
195 0x00000000 & Yes & Boot ROM (NOR Flash) \\
196 \hline
197 0x20000000 & Yes & On-chip SRAM \\
198 \hline
199 0x40000000 & Yes & \textit{FastMemoryLink bridge} \\
200 \hline
201 \hspace{5mm} 0x40000000 & Yes & \hspace{5mm} DDR SDRAM data \\
202 \hline
203 \hspace{5mm} 0x44000000 & Yes (write-through) & \hspace{5mm} L2 cache line flush \\
204 \hline
205 0x80000000 & No & \textit{CSR bridge} \\
206 \hline
207 \hspace{5mm} 0x80000000 & No & \hspace{5mm} UART \\
208 \hline
209 \hspace{5mm} 0x80001000 & No & \hspace{5mm} System controller \\
210 \hline
211 \hspace{5mm} 0x80002000 & No & \hspace{5mm} DDR SDRAM control \\
212 \hline
213 \hspace{5mm} 0x80003000 & No & \hspace{5mm} VGA \\
214 \hline
215 \hspace{5mm} 0x80004000 & No & \hspace{5mm} AC'97 \\
216 \hline
217 \hspace{5mm} 0x80005000 & No & \hspace{5mm} PFPU \\
218 \hline
219 \hspace{5mm} 0x80006000 & No & \hspace{5mm} TMU \\
220 \hline
221 \hspace{5mm} 0x80007000 & No & \hspace{5mm} PS/2 (ML401 only) \\
222 \hline
223 0xa0000000 & No & SystemACE (ML401 only) \\
224 \hline
225 \end{tabularx}
226
227 \section{IRQ map}
228 \begin{tabularx}{\textwidth}{|l|X|}
229 \hline
230 \bf{IRQ} & \bf{Peripheral} \\
231 \hline
232 0 & GPIO \\
233 \hline
234 1 & Timer 0 \\
235 \hline
236 2 & Timer 1 \\
237 \hline
238 3 & UART (RX)\\
239 \hline
240 4 & UART (TX)\\
241 \hline
242 5 & AC'97 (codec configuration registers, request sent)\\
243 \hline
244 6 & AC'97 (codec configuration registers, reply received)\\
245 \hline
246 7 & AC'97 (DMA read)\\
247 \hline
248 8 & AC'97 (DMA write)\\
249 \hline
250 9 & Programmable Floating Point Unit\\
251 \hline
252 10 & Texture Mapping Unit\\
253 \hline
254 11 & PS/2 (ML401 only)\\
255 \hline
256 \end{tabularx}
257
258 \section{BIOS and boot process}
259 Using an ``execute-in-place'' schema, the system boots from the NOR flash, mapped at address 0x00000000 (the reset vector for the softcore CPU). It contains a BIOS which is in charge of booting the board as well as providing debugging features.
260
261 The Milkymist BIOS is based on FreeMAC (\url{http://lekernel.net/prism54/freemac.html}), originally written for running on the ARM embedded processors of Prism54 Wi-Fi cards. It has undergone major modifications since then.
262
263 The BIOS loads firmware from an external source (CF card or UART). The BIOS supports direct booting of Linux kernels. If no suitable boot medium is found, it starts a debug shell on the UART, which allows to do basic system operations such as writing to registers. The \verb!help! command lists the commands available with the BIOS release you are currently using.
264
265 All transmissions over the UART are made at 115200 bps or 230400 bps, with 8 bits per character, without parity, and with 1 stop bit. The second DIP switch on the board enables the 230400 bps rate when it is set, which is convenient when transferring large firmware images such as Linux kernels.
266
267 \subsection{Starting Linux}
268 The BIOS can directly start versions of Linux specifically made for running on Milkymist boards. Such modified Linux kernels are distributed separately.
269
270 \begin{itemize}
271 \item \textbf{The Linux kernel itself} is always loaded at the beginning of the SDRAM (0x40000000) and executed from there.
272 \item \textbf{Kernel command line parameters} are written to SDRAM and their address is set in CPU register \verb!r1! before the kernel is started.
273 \item \textbf{Initial ramdisk (initrd)} is optionally loaded into SDRAM and its start and end addresses are set in CPU registers \verb!r2! and \verb!r3!, respectively.
274 \end{itemize}
275
276 \subsection{Boot from the UART}
277 The first boot medium tried by the BIOS is the UART, using a special protocol. This enables firmware replacement during development by just connecting the serial cable and not switching a memory card between a computer and the device.
278
279 The device initiates an UART boot session by sending the ASCII string \verb!sL5DdSMmkekro! followed by a carriage return. This string is completely random, but has been encoded in ASCII so it does not garble the output of terminals which are not aware of the boot protocol.
280
281 Upon reception of this magic string, the UART boot program running on the host computer acknowledges it by returning the ASCII string \verb!z6IHG7cYDID6o! followed by a carriage return. This puts the device in firmware reception mode, and further commands are sent in binary using the protocol described below.
282
283 The host sends command to the device, which acknowledges them or reports errors by sending one ASCII character after each command. Those characters and their meanings are listed in the table below:\\
284
285 \begin{tabular}{|l|l|}
286 \hline
287 \verb!K! & Command successful \\
288 \hline
289 \verb!C! & CRC error, retry the command \\
290 \hline
291 \verb!U! & Unknown command ID \\
292 \hline
293 \verb!E! & Generic error \\
294 \hline
295 \end{tabular}\\
296
297 The host must wait for a reply from the device before sending the next command. However, it can retry the command after a timeout.
298
299 All the commands sent by the host are frames using this common format:\\
300
301 \begin{tabular}{|l|l|l|l|}
302 \hline
303 \textbf{Length} & \textbf{CRC16} & \textbf{Command ID} & \textbf{Payload} \\
304 \hline
305 1 byte & 2 bytes & 1 byte & 0-255 bytes \\
306 \hline
307 \end{tabular}\\
308
309 (As in the whole document, all multi-byte numbers are big-endian unless otherwise specified)
310
311 The length field is the length of the payload. The CRC16 is computed on the command ID followed by the payload.
312
313 The following commands are implemented:\\
314
315 \begin{tabularx}{\textwidth}{|l|X|}
316 \hline
317 \textbf{Command ID} & \textbf{Description} \\
318 \hline
319 0x00 & Abort session. No payload. The BIOS continues to the next boot medium. \\
320 \hline
321 0x01 & Load to memory. The payload is a 32-bit start address followed by the data. \\
322 \hline
323 0x02 & Jump. The payload is the 32-bit jump address. \\
324 \hline
325 \multicolumn{2}{|c|}{\textbf{Linux-specific commands}} \\
326 \hline
327 0x03 & Set Linux kernel command line parameters address. The payload is the 32-bit address. This address is written to the CPU register r1 before the kernel is started (using a jump command). \\
328 \hline
329 0x04 & Set Linux kernel initrd start address. The payload is the 32-bit address. This address is written to the CPU register r2. \\
330 \hline
331 0x05 & Set Linux kernel initrd end address. The payload is the 32-bit address. This address is written to the CPU register r3. \\
332 \hline
333 \end{tabularx}
334
335 \subsection{Boot from the CF card}
336 If the device has not received an acknowledgement for UART boot after a certain period of time, it then attempts to boot from the CF card.
337
338 For this purpose, it searches for a file named \verb!BOOT.BIN! on the first FAT partition. It then loads it into the beginning of the SDRAM, and, if this was successful, transfers execution to the SDRAM.
339
340 If the first DIP switch on the board is set, the BIOS uses the \verb!ALTBOOT.BIN! file instead.
341
342 \paragraph{Linux support.} If the CF card also contains files named \verb!CMDLINE.TXT! and \verb!INITRD.BIN!, they are loaded into SDRAM at offsets \verb!0x1000000! (16MB) and \verb!0x1002000! (16MB + 8KB) respectively. The addresses are then passed to the kernel (loaded from \verb!BOOT.BIN! or \verb!ALTBOOT.BIN!) using CPU registers \verb!r1!, \verb!r2! and \verb!r3! (see above). The files must be small enough so that they do not overlap in memory.
343
344 \end{document}