1262ad4d0ca9c6374d362f3d26a31b45ddd30c9c
[mw/milkymist.git] / README
1 [> Milkymist(tm) system-on-chip
2 -------------------------------
3
4 This is the complete core source code and documentation for the opensource
5 system-on-chip used in the Milkymist(tm) interactive VJ station.
6
7 For the latest releases, binary distributions and more:
8   http://www.milkymist.org
9
10
11 [> Directory Structure
12  /cores/      Cores library, with Verilog sources, test benches and documentation.
13  /boards/     Top-level design files, constraint files and Makefiles
14               for supported FPGA boards.
15  /software/   Software for the SoC.
16  /std/        Definitions for Milkymist protocols and formats.
17  /doc/        System documentation.
18  /tools/      Small tools for developers.
19  /patches/    Example patches.
20
21
22 [> Building tools
23 You will need:
24  - GNU Make,
25  - Bourne Again Shell (bash),
26  - Xilinx ISE for synthesizing the FPGA bitstream (WebPack is enough),
27  - LatticeMico32 toolchain for building the SoC software,
28 For the host-side tools:
29  - native Clang/LLVM toolchain,
30  - libGD,
31 For the demonstration firmware:
32  - RE2C,
33  - Lemon parser generator,
34  - Scilab.
35
36 In case of Xst bugs or to improve timing/area (optional):
37  - Synplify Pro (Synopsys),
38  - or Precision RTL (Mentor Graphics).
39
40 NB. Before switching synthesis tools, don't forget to run "make clean" in the
41 synthesis directory.
42
43
44 [> Scripts
45 [>> Building
46  /boards/xxx/synthesis/build/system.bit build_bitstream.sh FPGA bitstream.
47  /software/bios/bios_splash.bin         build_bios.sh      BIOS image.
48  /software/demo/boot.bin                build_demo.sh      Demonstration firmware image.
49  /doc/xxx.pdf                           build_doc.sh       System-wide documentation.
50  /cores/xxx/doc/xxx.pdf                 build_doc.sh       Core-specific documentation.
51
52 [>> Loading
53  - load_bitstream.sh  : loads bitstream in volatile memory.
54  - flash_bitstream.sh : loads bitstream in non-volatile memory.
55  - flash_bios.sh      : loads BIOS into NOR flash (currently no way of storing it
56                         in volatile memory).
57  - load_demo.sh       : runs a SFL server and terminal program that downloads the
58                         demo firmware at device boot.
59
60
61 [> Quickstart
62 1- connect serial and JTAG cables
63 2- connect VGA monitor
64 3- build & load:
65 ./build_bitstream.sh
66 ./build_bios.sh
67 ./build_demo.sh
68 ./flash_bios.sh
69 ./load_demo.sh # will stay attached to display system debug messages
70 ./load_bitstream.sh # from another terminal
71
72 # if you like it
73 ./flash_bitstream.sh
74 cp software/demo/image.bin /memory_card/
75
76
77 [> Development
78 For Verilog simulations, the scripts (usually Makefiles) shipped with the test benches 
79 take care of running the simulator.
80
81 Depending on the IP core, one or more of these free simulators are supported:
82  - Icarus Verilog (http://www.icarus.com/eda/verilog/)
83  - GPL Cver (http://www.pragmatic-c.com/gpl-cver/)
84  - Verilator (http://www.veripool.org/wiki/verilator)
85
86 For firmware development, a serial console program compatible with automatic firmware
87 loading over the serial line (SFL boot) is provided in the /tools/ directory.
88
89
90 [> Credits
91 Most of the work is (C) Copyright 2007, 2008, 2009, 2010 Sebastien Bourdeauducq.
92 For this work:
93  - The hardware design is licensed under GNU GPLv3.
94    See the LICENSE.GPL file for more information.
95  - The software (software/*) is licensed under GNU GPLv3.
96    See LICENSE.GPL.
97  - The documentation is licensed under FDL.
98    See LICENSE.FDL.
99
100 Milkymist is a trademark of Sebastien Bourdeauducq.
101
102 The SoC design uses:
103  - the Mico32 soft-processor by Lattice Semiconductor. See the LICENSE.LATTICE file.
104  - a modified version of wb_conbus by Johny Chi and Rudolf Usselmann. See LICENSE.LGPL.
105
106 The directory organization and build scripts were inspired by soc-lm32 by the German
107 hackerspace Das Labor. Some of the UART and timer code also comes from there.
108
109 The software and software library include:
110  - the SoftFloat IEC/IEEE Floating-point Arithmetic Package, Release 2,
111    written by John R. Hauser. See source files headers for license.
112  - fundamental functions library by Jesus Calvino-Fraga. See the LICENSE.LGPL file.
113  - line drawing code from the GD library. See the LICENSE.GD file.
114
115 Special thanks to the people who did significant things which made this project possible:
116  - Lattice Semiconductor for the Mico32 processor,
117  - Shawn Tan for the AEMB processor (used earlier),
118  - Stephen Williams for Icarus Verilog,
119  - Pragmatic C Software for GPL Cver,
120  - Wilson Snyder for Verilator,
121  - Henry from Xilinx,
122  - Das Labor for providing neat build scripts for SoCs (soc-lm32).
123
124
125 [> Contact
126 E-mail: sebastien.bourdeauducq at lekernel daaht net
127 Phone:  +33(0)606644335
128 PGP:    0x9277FCF2
129
130 -----BEGIN PGP PUBLIC KEY BLOCK-----
131 Version: GnuPG v1.4.9 (GNU/Linux)
132
133 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
168 lRHoJGwiAJ9JnmgPtl71/XVNcFxNQqUxVTOvjg==
169 =NnZi
170 -----END PGP PUBLIC KEY BLOCK-----