diff --git a/README.md b/README.md index 5c5094b..06a09fc 100644 --- a/README.md +++ b/README.md @@ -3,16 +3,16 @@ ## WHAT IS REDUCERON? Reduceron is a high performance FPGA softcore for running lazy functional -programs, complete with hardware garbage collection. Reduceron has been +programs, complete with hardware garbage collection. Reduceron has been implemented on various FPGAs with clock frequency ranging from 60 to 150 -MHz depending on the FPGA. A high degree of parallelism allows Reduceron +MHz depending on the FPGA. A high degree of parallelism allows Reduceron to implement graph evaluation very efficiently. Reduceron is the work of Matthew Naylor, Colin Runciman and Jason Reich, -who have kindly made their work available for others to use. Please see -http://www.cs.york.ac.uk/fp/reduceron for supporting articles, memos, and -original distribution. - +who have kindly made their work available for others to use. Please see +https://mn416.github.io/reduceron-project/ (the original +http://www.cs.york.ac.uk/fp/reduceron no longer works) for supporting +articles, memos, and original distribution. ## OK, WHAT'S THIS THEN? @@ -22,40 +22,37 @@ can be useful for embedded projects and more. The York Reduceron needs the following enhancements to meet our needs: - 0. The heap and program must (for the most parts) be kept in external +0. The heap and program must (for the most parts) be kept in external memory, with FPGA block memory used for the stacks and heap and program caches. This simultaneously enables smaller and less expensive FPGAs to be used as well as allows for a much larger heap and larger programs. - 1. Access to memory mapped IO devices (and optionally, RAM). +1. Access to memory mapped IO devices (and optionally, RAM). - 2. Richer set of primitives, including multiplication, shifts, logical +2. Richer set of primitives, including multiplication, shifts, logical and, or, ... - 3. Support for 32-bit integers - this greatly simplifies interfacing to +3. Support for 32-bit integers - this greatly simplifies interfacing to existing IO devices and simplifies various numerical computations. - 4. Stack, update stack, [and case table stack?] should overflow +4. Stack, update stack, [and case table stack?] should overflow into/underflow from external, allowing for orders of magnitude larger structures. - While Reduceron technically refers to the FPGA implementation, it is supported by - - Flite: the F-lite to Red translator. - - A Red emulator in C - - Red Lava: Reduceron is a Red Lava program, which generate Verilog - - Support for Verilog simulation and synthesis for various FPGA boards - +- Flite: the F-lite to Red translator. +- A Red emulator in C +- Red Lava: Reduceron is a Red Lava program, which generate Verilog +- Support for Verilog simulation and synthesis for various FPGA boards As much of the history as was available has been gathered and Reduceron, Lava, and the Flite distribution have been merged into one repository. - ## HOW DO I USE IT? The 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 regression run will start. The Verilog simulation part will take weeks to finish. -To build: +### Prerequisites + +#### 1. **Stack** + +Install Stack, the Haskell build tool: + +```bash +wget -qO- https://get.haskellstack.org/ | sh +``` + +#### 2. **Cabal** + +Install Cabal using Stack: + +```bash +stack --resolver=lts-12.26 install Cabal +``` + +#### 3. **Verilog Simulation Tools** + +Install Verilator and Icarus Verilog: - make +```bash +sudo apt-get update +sudo apt-get install verilator iverilog +``` -Or run a specific test suite: +### Building the Project - make -C programs $X +Reduceron uses Stack for managing Haskell dependencies. To ensure the environment is correctly set up: + +#### 1. **Initialize Stack for Flite** + +```bash +cd flite +stack init +stack build +cd .. +``` + +#### 2. **Compile with Make** + +```bash +stack --resolver=lts-12.26 exec make +``` + +Or alternalitvely: + +```bash +make +``` + +To run a specific test suite: + +```bash +make -C programs $X +``` where $X is one of `regress-emu`, `regress-flite-sim`, `regress-flite-comp`, or `regress-red-verilog-sim`. Note: the code generated by the C backend for Flite (used in the `regress-flite-comp`) depends on GCC features, such as nested -functions. To build on macOS, install *real* gcc (say via Mac +functions. To build on macOS, install _real_ gcc (say via Mac Homebrew) and invoke make as `make CC=gcc-7` (assuming you installed version 7 of gcc). To build a hardware version of a given test +```bash +cd fpga; +make && flite -r ../programs/$P | ./Red -v +``` - cd fpga; make && flite -r ../programs/$P | ./Red -v - -where $P is one of the programs (.hs). Next, build a Reduceron system +where $P is one of the programs (.hs). Next, build a Reduceron system for an FPGA board, fx the BeMicroCV A9: - make -C Reduceron/BeMicroCV-A9 +```bash +make -C Reduceron/BeMicroCV-A9 +``` Unfortunately programs can't currently be loaded dynamically but are -baked into the FPGA image. It's a high priority goal to change that. +baked into the FPGA image. It's a high priority goal to change that. ## WHERE IS THIS GOING? -### Plan ### +### Plan - 1. Port to Verilog and remove Xilinx-isms. DONE! +1. Port to Verilog and remove Xilinx-isms. DONE! - 2. Shrink to fit mid-sized FPGA kits (eg. DE2-115 and BeMicroCV-A9). - DONE! +2. Shrink to fit mid-sized FPGA kits (eg. DE2-115 and BeMicroCV-A9). + DONE! - 3. Rework Lava and the Reduceron implementation to be more - composable and elastic; this means fewer or no global assumptions - about timing. ONGOING! +3. Rework Lava and the Reduceron implementation to be more + composable and elastic; this means fewer or no global assumptions + about timing. ONGOING! - 4. Support load/store to an external bus (the key difficulty is - stalling while waiting on the bus). +4. Support load/store to an external bus (the key difficulty is + stalling while waiting on the bus). - 5. Use the program memory as a cache, making programs dynamically - loadable and dramatically raise the size limits. +5. Use the program memory as a cache, making programs dynamically + loadable and dramatically raise the size limits. -### Eventual Plan ### +### Eventual Plan - - Move the heap [and tospace] to external memory - - Add a heap cache/newspace memory - - Implement the emu-32.c representation for the external heap - - Much richer primitives - - Haskell front-end +- Move the heap [and tospace] to external memory +- Add a heap cache/newspace memory +- Implement the emu-32.c representation for the external heap +- Much richer primitives +- Haskell front-end -### Long Term Plan ### +### Long Term Plan - - Research the design space; explore parallelism +- Research the design space; explore parallelism ## OPEN QUESTIONS, with answers from Matthew: Q1: Currently there doesn't seem an efficient way to handle toplevel - variable bindings (CAFs). What did the York team have in mind there - or does it require an extension? (Obviously one can treat them all - other functional arguments, but that would mean a lot of parameters - to pass around). +variable bindings (CAFs). What did the York team have in mind there +or does it require an extension? (Obviously one can treat them all +other functional arguments, but that would mean a lot of parameters +to pass around). A1: "Some mechanism would be needed to construct graphs at a specified -location on the heap at the beginning of program execution. The +location on the heap at the beginning of program execution. The initial (unevaluated) graphs have constant size so can be linked to at compile time." - -Q2: Why does Flite default to 0 for the MAXREGS parameter? Eg, why is +Q2: Why does Flite default to 0 for the MAXREGS parameter? Eg, why is redDefaults = CompileToRed 6 4 2 1 0 A2: (Historical reasons it would appear). - Q3: What happend to Memo 24? A3: "I'd like to say it was our best kept secret, but in reality it diff --git a/flite/Makefile b/flite/Makefile index cdfcfe4..46d4924 100644 --- a/flite/Makefile +++ b/flite/Makefile @@ -1,3 +1,3 @@ dist/build/Flite/flite.always: - cabal configure - cabal $(J) build + stack --resolver=lts-12.26 install Cabal + stack --resolver=lts-12.26 build diff --git a/flite/flite.cabal b/flite/flite.cabal index a5f4944..2c6b1e0 100644 --- a/flite/flite.cabal +++ b/flite/flite.cabal @@ -8,7 +8,7 @@ Maintainer: Jason Reich , Matthew Naylor =1.6 +Cabal-Version: >=1.8 Description: The f-lite language is a subset of Haskell 98 and Clean consisting of function definitions, pattern matching, limited let expressions, function applications and constructor applications expressed in the explicit 'braces' layout-insensitive format. @@ -32,7 +32,7 @@ Executable flite Flite.InterpFrontend, Flite.LambdaLift, Flite.Let, Flite.Matching, Flite.Predex, Flite.Pretty, Flite.RedCompile, Flite.RedFrontend, Flite.RedSyntax, Flite.State, Flite.Strictify, Flite.Syntax, - Flite.Traversals, Flite.Writer, Flite.Writer, Flite.WriterState, + Flite.Traversals, Flite.Writer, Flite.WriterState, Flite.Parsec.Parse, Flite.Parsec.Flite, Flite.Parsec.Prelude, Flite.Dependency, Flite.IntInfer, Flite.Strictness, Flite.WorkerWrapper, Paths_flite diff --git a/flite/stack.yaml b/flite/stack.yaml new file mode 100644 index 0000000..1620b4f --- /dev/null +++ b/flite/stack.yaml @@ -0,0 +1,67 @@ +# This file was automatically generated by 'stack init' +# +# Some commonly used options have been documented as comments in this file. +# For advanced use and comprehensive documentation of the format, please see: +# https://docs.haskellstack.org/en/stable/yaml_configuration/ + +# A 'specific' Stackage snapshot or a compiler version. +# A snapshot resolver dictates the compiler version and the set of packages +# to be used for project dependencies. For example: +# +# snapshot: lts-22.28 +# snapshot: nightly-2024-07-05 +# snapshot: ghc-9.6.6 +# +# The location of a snapshot can be provided as a file or url. Stack assumes +# a snapshot provided as a file might change, whereas a url resource does not. +# +# snapshot: ./custom-snapshot.yaml +# snapshot: https://example.com/snapshots/2024-01-01.yaml +snapshot: + url: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/23/0.yaml + +# User packages to be built. +# Various formats can be used as shown in the example below. +# +# packages: +# - some-directory +# - https://example.com/foo/bar/baz-0.0.2.tar.gz +# subdirs: +# - auto-update +# - wai +packages: +- . +# Dependency packages to be pulled from upstream that are not in the snapshot. +# These entries can reference officially published versions as well as +# forks / in-progress versions pinned to a git hash. For example: +# +# extra-deps: +# - acme-missiles-0.3 +# - git: https://github.com/commercialhaskell/stack.git +# commit: e7b331f14bcffb8367cd58fbfc8b40ec7642100a +# +# extra-deps: [] + +# Override default flag values for project packages and extra-deps +# flags: {} + +# Extra package databases containing global packages +# extra-package-dbs: [] + +# Control whether we use the GHC we find on the path +# system-ghc: true +# +# Require a specific version of Stack, using version ranges +# require-stack-version: -any # Default +# require-stack-version: ">=3.1" +# +# Override the architecture used by Stack, especially useful on Windows +# arch: i386 +# arch: x86_64 +# +# Extra directories used by Stack for building +# extra-include-dirs: [/path/to/dir] +# extra-lib-dirs: [/path/to/dir] +# +# Allow a newer minor version of GHC than the snapshot specifies +# compiler-check: newer-minor diff --git a/flite/stack.yaml.lock b/flite/stack.yaml.lock new file mode 100644 index 0000000..a4edf3e --- /dev/null +++ b/flite/stack.yaml.lock @@ -0,0 +1,13 @@ +# This file was autogenerated by Stack. +# You should not edit this file by hand. +# For more information, please see the documentation at: +# https://docs.haskellstack.org/en/stable/lock_files + +packages: [] +snapshots: +- completed: + sha256: 9444fadfa30b67a93080254d53872478c087592ad64443e47c546cdcd13149ae + size: 678857 + url: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/23/0.yaml + original: + url: https://raw.githubusercontent.com/commercialhaskell/stackage-snapshots/master/lts/23/0.yaml diff --git a/programs/Makefile b/programs/Makefile index 8a3da9c..4804bb4 100644 --- a/programs/Makefile +++ b/programs/Makefile @@ -11,7 +11,8 @@ BENCHLOADS=Cichelli Braun OrdList Queens2 MSS Queens PermSort SumPuz Mate2 Mate EMU=../emulator/emu # XXX this is broken now as cabal has change; FIXME -FLITE=../flite/dist/build/flite/flite +FLITE=$(shell find ../flite/.stack-work -name flite -type f -not -type d | head -n 1) +$(info $(FLITE)) FLITE_RED=-r6:4:2:1:8 -i1 -s # Surprisingly there isn't a clear winner among h[0-3] i[0-3] s[0-1], # but this came out ahead @@ -37,7 +38,7 @@ bench: bench-flite-c-comp $(EMU): ../emulator/emu.c $(MAKE) -C ../emulator emu -$(FLITE): flite.built +$(FLITE): $(MAKE) -C ../flite touch flite.built