Add README and LICENSE

LICENSE

@@ -0,0 +1,13 @@
+Copyright (c) 2017-2018 Graham Edgecombe <gpe@grahamedgecombe.com>
+
+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.

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/