33## WHAT IS REDUCERON?
44
55Reduceron is a high performance FPGA softcore for running lazy functional
6- programs, complete with hardware garbage collection. Reduceron has been
6+ programs, complete with hardware garbage collection. Reduceron has been
77implemented on various FPGAs with clock frequency ranging from 60 to 150
8- MHz depending on the FPGA. A high degree of parallelism allows Reduceron
8+ MHz depending on the FPGA. A high degree of parallelism allows Reduceron
99to implement graph evaluation very efficiently.
1010
1111Reduceron is the work of Matthew Naylor, Colin Runciman and Jason Reich,
12- who have kindly made their work available for others to use. Please see
13- http ://www.cs.york.ac.uk/fp/ reduceron for supporting articles, memos, and
14- original distribution.
15-
12+ who have kindly made their work available for others to use. Please see
13+ https ://mn416.github.io/ reduceron-project/ (the original
14+ http://www.cs.york.ac.uk/fp/reduceron no longer works) for supporting
15+ articles, memos, and original distribution.
1616
1717## OK, WHAT'S THIS THEN?
1818
@@ -22,40 +22,37 @@ can be useful for embedded projects and more.
2222
2323The York Reduceron needs the following enhancements to meet our needs:
2424
25- 0 . The heap and program must (for the most parts) be kept in external
25+ 0 . The heap and program must (for the most parts) be kept in external
2626 memory, with FPGA block memory used for the stacks and heap and
2727 program caches.
2828
2929 This simultaneously enables smaller and less expensive FPGAs to be
3030 used as well as allows for a much larger heap and larger programs.
3131
32- 1 . Access to memory mapped IO devices (and optionally, RAM).
32+ 1 . Access to memory mapped IO devices (and optionally, RAM).
3333
34- 2 . Richer set of primitives, including multiplication, shifts, logical
34+ 2 . Richer set of primitives, including multiplication, shifts, logical
3535 and, or, ...
3636
37- 3 . Support for 32-bit integers - this greatly simplifies interfacing to
37+ 3 . Support for 32-bit integers - this greatly simplifies interfacing to
3838 existing IO devices and simplifies various numerical computations.
3939
40- 4 . Stack, update stack, [ and case table stack?] should overflow
40+ 4 . Stack, update stack, [ and case table stack?] should overflow
4141 into/underflow from external, allowing for orders of magnitude
4242 larger structures.
4343
44-
4544While Reduceron technically refers to the FPGA implementation, it is
4645supported by
4746
48- - Flite: the F-lite to Red translator.
49- - A Red emulator in C
50- - Red Lava: Reduceron is a Red Lava program, which generate Verilog
51- - Support for Verilog simulation and synthesis for various FPGA boards
52-
47+ - Flite: the F-lite to Red translator.
48+ - A Red emulator in C
49+ - Red Lava: Reduceron is a Red Lava program, which generate Verilog
50+ - Support for Verilog simulation and synthesis for various FPGA boards
5351
5452As much of the history as was available has been gathered and
5553Reduceron, Lava, and the Flite distribution have been merged into one
5654repository.
5755
58-
5956## HOW DO I USE IT?
6057
6158The was last tested with Glasgow Haskell Compiler, Version 8.4.4 on
@@ -65,87 +62,139 @@ Optionally: just run make in the toplevel directory and a large
6562regression run will start. The Verilog simulation part will take weeks to
6663finish.
6764
68- To build:
65+ ### Prerequisites
66+
67+ #### 1. ** Stack**
68+
69+ Install Stack, the Haskell build tool:
70+
71+ ``` bash
72+ wget -qO- https://get.haskellstack.org/ | sh
73+ ```
74+
75+ #### 2. ** Cabal**
76+
77+ Install Cabal using Stack:
78+
79+ ``` bash
80+ stack --resolver=lts-12.26 install Cabal
81+ ```
82+
83+ #### 3. ** Verilog Simulation Tools**
84+
85+ Install Verilator and Icarus Verilog:
6986
70- make
87+ ``` bash
88+ sudo apt-get update
89+ sudo apt-get install verilator iverilog
90+ ```
7191
72- Or run a specific test suite:
92+ ### Building the Project
7393
74- make -C programs $X
94+ Reduceron uses Stack for managing Haskell dependencies. To ensure the environment is correctly set up:
95+
96+ #### 1. ** Initialize Stack for Flite**
97+
98+ ``` bash
99+ cd flite
100+ stack init
101+ stack build
102+ cd ..
103+ ```
104+
105+ #### 2. ** Compile with Make**
106+
107+ ``` bash
108+ stack --resolver=lts-12.26 exec make
109+ ```
110+
111+ Or alternalitvely:
112+
113+ ``` bash
114+ make
115+ ```
116+
117+ To run a specific test suite:
118+
119+ ``` bash
120+ make -C programs $X
121+ ```
75122
76123where $X is one of ` regress-emu ` , ` regress-flite-sim ` , ` regress-flite-comp ` , or
77124` regress-red-verilog-sim ` .
78125
79126Note: the code generated by the C backend for Flite (used in the
80127` regress-flite-comp ` ) depends on GCC features, such as nested
81- functions. To build on macOS, install * real * gcc (say via Mac
128+ functions. To build on macOS, install _ real _ gcc (say via Mac
82129Homebrew) and invoke make as ` make CC=gcc-7 ` (assuming you installed
83130version 7 of gcc).
84131
85132To build a hardware version of a given test
133+ ``` bash
134+ cd fpga;
135+ make && flite -r ../programs/$P | ./Red -v
136+ ```
86137
87- cd fpga; make && flite -r ../programs/$P | ./Red -v
88-
89- where $P is one of the programs (.hs). Next, build a Reduceron system
138+ where $P is one of the programs (.hs). Next, build a Reduceron system
90139for an FPGA board, fx the BeMicroCV A9:
91140
92- make -C Reduceron/BeMicroCV-A9
141+ ``` bash
142+ make -C Reduceron/BeMicroCV-A9
143+ ```
93144
94145Unfortunately programs can't currently be loaded dynamically but are
95- baked into the FPGA image. It's a high priority goal to change that.
146+ baked into the FPGA image. It's a high priority goal to change that.
96147
97148## WHERE IS THIS GOING?
98149
99- ### Plan ###
150+ ### Plan
100151
101- 1 . Port to Verilog and remove Xilinx-isms. DONE!
152+ 1 . Port to Verilog and remove Xilinx-isms. DONE!
102153
103- 2 . Shrink to fit mid-sized FPGA kits (eg. DE2-115 and BeMicroCV-A9).
104- DONE!
154+ 2 . Shrink to fit mid-sized FPGA kits (eg. DE2-115 and BeMicroCV-A9).
155+ DONE!
105156
106- 3 . Rework Lava and the Reduceron implementation to be more
107- composable and elastic; this means fewer or no global assumptions
108- about timing. ONGOING!
157+ 3 . Rework Lava and the Reduceron implementation to be more
158+ composable and elastic; this means fewer or no global assumptions
159+ about timing. ONGOING!
109160
110- 4 . Support load/store to an external bus (the key difficulty is
111- stalling while waiting on the bus).
161+ 4 . Support load/store to an external bus (the key difficulty is
162+ stalling while waiting on the bus).
112163
113- 5 . Use the program memory as a cache, making programs dynamically
114- loadable and dramatically raise the size limits.
164+ 5 . Use the program memory as a cache, making programs dynamically
165+ loadable and dramatically raise the size limits.
115166
116- ### Eventual Plan ###
167+ ### Eventual Plan
117168
118- - Move the heap [ and tospace] to external memory
119- - Add a heap cache/newspace memory
120- - Implement the emu-32.c representation for the external heap
121- - Much richer primitives
122- - Haskell front-end
169+ - Move the heap [ and tospace] to external memory
170+ - Add a heap cache/newspace memory
171+ - Implement the emu-32.c representation for the external heap
172+ - Much richer primitives
173+ - Haskell front-end
123174
124- ### Long Term Plan ###
175+ ### Long Term Plan
125176
126- - Research the design space; explore parallelism
177+ - Research the design space; explore parallelism
127178
128179## OPEN QUESTIONS, with answers from Matthew:
129180
130181Q1: Currently there doesn't seem an efficient way to handle toplevel
131- variable bindings (CAFs). What did the York team have in mind there
132- or does it require an extension? (Obviously one can treat them all
133- other functional arguments, but that would mean a lot of parameters
134- to pass around).
182+ variable bindings (CAFs). What did the York team have in mind there
183+ or does it require an extension? (Obviously one can treat them all
184+ other functional arguments, but that would mean a lot of parameters
185+ to pass around).
135186
136187A1: "Some mechanism would be needed to construct graphs at a specified
137- location on the heap at the beginning of program execution. The
188+ location on the heap at the beginning of program execution. The
138189initial (unevaluated) graphs have constant size so can be linked to at
139190compile time."
140191
141-
142- Q2: Why does Flite default to 0 for the MAXREGS parameter? Eg, why is
192+ Q2: Why does Flite default to 0 for the MAXREGS parameter? Eg, why is
143193
144194 redDefaults = CompileToRed 6 4 2 1 0
145195
146196A2: (Historical reasons it would appear).
147197
148-
149198Q3: What happend to Memo 24?
150199
151200A3: "I'd like to say it was our best kept secret, but in reality it
0 commit comments