From a1fb770982208d7a813f328d4886a2efc39f215c Mon Sep 17 00:00:00 2001 From: Graham Edgecombe Date: Thu, 4 Jan 2018 22:04:40 +0000 Subject: [PATCH] Add README and LICENSE --- LICENSE | 13 ++++++++ README.md | 94 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 107 insertions(+) create mode 100644 LICENSE create mode 100644 README.md diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..173bc1d --- /dev/null +++ b/LICENSE @@ -0,0 +1,13 @@ +Copyright (c) 2017-2018 Graham Edgecombe + +Permission to use, copy, modify, and/or distribute this software for any +purpose with or without fee is hereby granted, provided that the above +copyright notice and this permission notice appear in all copies. + +THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..465efcb --- /dev/null +++ b/README.md @@ -0,0 +1,94 @@ +# Icicle + +## Introduction + +Icicle is a 32-bit [RISC-V][riscv] system on chip for [iCE40 HX8K][ice40] FPGAs. +It can be built with the open-source [Project IceStorm][icestorm] toolchain and +currently targets the [iCE40-HX8K breakout board][ice40-hx8k-breakout]. + +## Current features + +* RV32I core with a [classic 5-stage RISC pipeline][classic-risc], static branch + prediction, bypassing and interlocking. It currently implements the entire + [user ISA][riscv-user] (except `ECALL` and `EBREAK`) and parts of the + [privileged ISA][riscv-priv]. +* Shared instruction and data memory (8 KiB, implemented with FPGA block RAM). +* Memory-mapped UART and LEDs. + +## Dependencies + +* [arachne-pnr][arachne-pnr] +* [GNU RISC-V toolchain][riscv-gnu] +* [GNU Make][make] +* [Icarus Verilog][iverilog] +* [Project IceStorm][icestorm] +* [vim][vim] (for `xxd`) +* [Yosys][yosys] + +## Building and testing + +1. Run `make syntax` to check the syntax with [Icarus][iverilog], which has a + stricter parser than [Yosys][yosys]. +2. Run `make` to synthesize the design, place and route, compile the demo + program in `progmem.c` and create the bitstream. +3. Connect the [iCE40-HX8K breakout board][ice40-hx8k-breakout] and configure + the jumpers for direct SRAM programming. +4. Run `make flash` to program the bitstream. `icetime` is used to check that + the design meets timing closure. The target fails if it does not. +5. 4 of the 8 LEDs should turn on (with an on, off, on, off pattern). Run + `picocom /dev/ttyUSBN` (replacing `ttyUSBN` with the name of the serial port) + to connect to the serial port. `Hello, world!` should be printed once per + second. + +The `make stat` target runs `icebox_stat` and the `make time` target prints the +`icetime` report. + +The `Makefile` runs the [IceStorm][icestorm] toolchain in quiet mode. Unset the +`QUIET` variable to run the toolchain in verbose mode - e.g. `make QUIET=`. + +## Planned features + +* Use remaining block RAM tiles to eke out as much memory as possible. +* Implement remaining bits of the user ISA. +* Implement machine mode from the privileged ISA. +* Interrupts/exceptions. +* Unaligned memory access support. +* Memory-mapped GPIOs. +* Memory-mapped XIP/SPI flash. +* Improved reset support (a reset signal + boot ROM to zero all the registers). +* Automated tests. +* Multiply/divide support. +* Compressed instruction support. + +## Size and performance + +The entire system on chip currently occupies around 2,000 LUTs on an iCE40 when +synthesized with [Yosys][yosys]. + +It's currently clocked at 24 MHz but `icetime` estimates it could be clocked at +~30-35 MHz (depending on how lucky [arachne-pnr][arachne-pnr] is). + +The core is capable of issuing and retiring one instruction per clock cycle, +although the actual number of instructions per cycle will be slightly less than +this in practice due to interlocking, branch mispredictions and the shared +memory bus. + +## License + +This project is available under the terms of the ISC license, which is similar +to the 2-clause BSD license. See the `LICENSE` file for the copyright +information and licensing terms. + +[arachne-pnr]: https://github.com/cseed/arachne-pnr +[classic-risc]: https://en.wikipedia.org/wiki/Classic_RISC_pipeline +[ice40-hx8k-breakout]: http://www.latticesemi.com/Products/DevelopmentBoardsAndKits/iCE40HX8KBreakoutBoard.aspx +[ice40]: http://www.latticesemi.com/Products/FPGAandCPLD/iCE40.aspx +[icestorm]: http://www.clifford.at/icestorm/ +[iverilog]: http://iverilog.icarus.com/ +[make]: https://www.gnu.org/software/make/ +[riscv-gnu]: https://github.com/riscv/riscv-gnu-toolchain +[riscv-priv]: https://riscv.org/specifications/privileged-isa/ +[riscv-user]: https://riscv.org/specifications/ +[riscv]: https://riscv.org/risc-v-isa/ +[vim]: http://www.vim.org/ +[yosys]: http://www.clifford.at/yosys/