{"id":16911017,"url":"https://github.com/thoughtpolice/claap","last_synced_at":"2025-10-03T13:36:47.580Z","repository":{"id":138307685,"uuid":"68057670","full_name":"thoughtpolice/claap","owner":"thoughtpolice","description":"\"An Altruistic Processor\", implemented in CLaSH (WARNING: incomplete code)","archived":false,"fork":false,"pushed_at":"2017-03-31T18:58:26.000Z","size":84,"stargazers_count":13,"open_issues_count":0,"forks_count":0,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-25T12:03:53.863Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Haskell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thoughtpolice.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS.txt","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-09-12T23:56:25.000Z","updated_at":"2019-12-05T06:34:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"f589bed3-fe43-4c46-870a-04df2a1b1881","html_url":"https://github.com/thoughtpolice/claap","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thoughtpolice%2Fclaap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thoughtpolice%2Fclaap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thoughtpolice%2Fclaap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thoughtpolice%2Fclaap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thoughtpolice","download_url":"https://codeload.github.com/thoughtpolice/claap/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248435458,"owners_count":21103032,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-13T19:04:12.217Z","updated_at":"2025-10-03T13:36:47.495Z","avatar_url":"https://github.com/thoughtpolice.png","language":"Haskell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CLAAP: An Altruistic Processor, implemented in CLaSH\n\n[![CircleCI](https://circleci.com/gh/thoughtpolice/claap/tree/master.svg?style=shield\u0026circle-token=af910f74f45f5868c0b3d82a37e1a0fc88232bc6)](https://circleci.com/gh/thoughtpolice/claap/tree/master)\n[![BSD3](https://img.shields.io/badge/License-BSD-blue.svg)](https://en.wikipedia.org/wiki/BSD_License)\n[![Haskell](https://img.shields.io/badge/Language-Haskell-yellowgreen.svg)](https://www.haskell.org)\n\n_CLAAP_ (\"**CL**aSH + **AAP**\") is an FPGA implementation of the [AAP][], a\n16-bit Harvard architecture processor, using\nthe [CLaSH](http://www.clash-lang.org) language: a compiler from Haskell to\nhardware description languages.\n\n[AAP]: http://www.embecosm.com/2015/04/20/aap-a-reference-harvard-architecture-for-embedded-compiler-development/\n\n#### Table of Contents\n\n- [Features](#features)\n- [Demo](#demo)\n- [FAQ](#faq)\n- [Building](#building)\n  - [Supported boards and synthesis flows](#supported-boards-and-synthesis-flows)\n  - [Environment setup](#environment-setup)\n  - [Configuring the build](#configuring-the-build)\n  - [Do one stupid thing first](#do-one-stupid-thing-first)\n  - [Running the build](#running-the-build)\n    - [Build artifacts](#build-artifacts)\n    - [Cleaning up](#cleaning-up)\n  - [Compiler toolchain](#compiler-toolchain)\n  - [Running the testbench](#running-the-testbench)\n  - [Uploading to your board](#uploading-to-your-board)\n- [Performance, timing, utilization](#performance-timing-utilization)\n  - [Performance notes](#performance-notes)\n  - [Timing and utilization](#timing-and-utilization)\n  - [Dhrystone](#dhrystone)\n- [References](#references)\n- [Join in](#join-in)\n- [Authors](#authors)\n- [License](#license)\n\n# Features\n\nHere's the basic elevator pitch:\n\n- Full 16-bit CPU written in 100% bona-fide Haskell\n  with [CLaSH](http://www.clash-lang.org), implementing the full AAP\n  instruction set.\n- Probably significantly worse than [picorv32][] in every comparable way.\n- The resulting CPU can be compiled to an executable for simulation,\n  (System)Verilog, ~~or VHDL~~. This resulting HDL is then \"massaged\"\n  by [Yosys][yosys] and stuffed into a single, re-usable Verilog file with a\n  top-level interface. The resulting HDL should be easy to integrate elsewhere.\n- Full 16 and 32-bit instruction support (AAP uses RISC-V style instruction\n  chaining to allow extension of instructions to arbitrary lengths).\n- Completely synthesizable with the open\n  source [IceStorm Flow][icestorm], for a fully open-source\n  HDL-to-hardware toolchain.\n  - Support for other flows ~~(and their horrible software)~~ coming soon!\n- Testable on real hardware - primary test board is\n  8k-LUT [iCE40-HX8K \"Breakout Board\"][8kbb].\n  - More boards coming soon!\n- ~~Completely synthesized test bench, for post place-and-route testing.~~\n  (TODO!)\n- A fast, dependable little build system, written with [Shake][shake].\n- Clean code that's easy to use.\n  - Well commented source. Everything has documentation.\n  - *Cosimulation support*: CLaSH supports *cosimulation*, meaning all\n    synthesizable Haskell code can also be executed natively -- you can quickly\n    compile all of the code to an executable and test it that way. Yet the\n    compiler can also generate HDL code -- and HDL test benches -- that are also\n    synthesizable. This allows trivial pre-synthesis testing, and allows post\n    place-and-route testing, all from one set of code. You can contribute even\n    if you have no hardware or synthesis tools!\n  - A simple, yet _modern_ Haskell codebase keeps things type safe and brief --\n    but _never_ at the cost of clarity and understanding.\n  - Loosely coupled - you can substitute components pretty easily, e.g. memory\n    units built on Block RAMs changed to one built on LUTs. Useful for\n    understanding the design of such components and testing new ones and\n    improvements against references.\n  - Perfect learning tool for weird people who know Haskell and want to learn\n    hardware design, or vice versa!\n  - Small: only TODO FIXME lines of code!\n- LLVM-based toolchain available to build working programs.\n- ~~Integration with [yosys-smtbmc][] for verification.~~ (TODO!)\n- Some extras include:\n  - Simple but fully usable disassembler - built on the *exact* same code as the\n    real instruction decoder that is synthesized to hardware and used to drive\n    the execution unit.\n  - Dhrystone benchmark port.\n  - ~~Full Assembler.~~\n- Seriously, [picorv32][] is probably much better instead.\n\n[picorv32]: https://github.com/cliffordwolf/picorv32\n[shake]: http://www.shakebuild.com\n[yosys-smtbmc]: http://www.clifford.at/papers/2016/yosys-synth-formal\n[yosys]: http://www.clifford.at/yosys/\n\nNaturally, CLAAP inherits all the features of AAP itself (from\nthe [AAP announcement][aap-ann]):\n\n[aap-ann]: http://www.embecosm.com/2015/04/20/aap-a-reference-harvard-architecture-for-embedded-compiler-development/\n\n- **16-bit RISC architecture**. The core design sticks to the RISC principles of\n  3-address register-to-register operation, a small number of operations and a\n  simple to implement datapath.  The fundamental data type is the 16-bit\n  integer.\n- **Configurable number of registers**. Although 32/64-bit RISC architectures\n  typically have 16 or more general purpose registers, small deeply embedded\n  processors often have far fewer. This represents a significant compiler\n  implementation challenge.  To allow exploration of this area, AAP can be\n  configured with between 4 and 64, 16-bit registers.\n- **Harvard memory layout**. The basic architecture provides a 64k byte\n  addressed data memory and a separate 16M word instruction memory.  By\n  requiring more than 16-bits to address the instruction memory, the compiler\n  writer can explore the challenge of pointers which are larger than the native\n  integer type. Deeply embedded systems often have very small memories,\n  particularly for data, so the size of memories can be configured.\n- **Multiple address spaces**. Many architectures also provide more than two\n  address spaces, often for special purposes.  For example a small EEPROM\n  alongside Flash memory, or the Special Purpose Register block of OpenRISC.\n  AAP can support additional address spaces, allowing support for multiple\n  address spaces throughout the tool chain to be explored.\n- **24-bit program counter with 8-bit status register**. AAP requires a 24-bit\n  program counter, which is held in a 32-bit register. The top bits of the\n  program counter then form a status register.  Jump instructions ignore these\n  top 8 bits. At present only one status bit is defined, a carry flag to allow\n  multiple precision arithmetic.\n- **16/32-bit instruction encoding**. A frequent feature of many architectures\n  is to provide a subset of the most commonly used parts of the Instruction Set\n  Architecutre (ISA) in a short encoding of 16-bits.  Less common instructions\n  are then encoded in 32-bits. Optimizing to use these shorter instructions, is\n  particularly important for compilers for embedded targets, where memory is at\n  a premium. AAP provides such a 16-bit subset with a 32-bit encoding of the\n  full ISA. However it follows the instruction chaining of RISC-V, so even\n  longer instructions could be created in the future.\n- **Three address code**. AAP has stuck rigidly to the RISC principle of\n  3-address instructions throughout.  Almost all instructions come in two\n  variants, one where the third argument is a register, and one where the third\n  argument is a constant.\n- **No flags for flow of control**. There are no flag registers indicating the\n  results of operations for use in conditional jumps.  Instead the operation is\n  encoded within the jump instruction itself. There is an 8-bit status register\n  as part of the program counter, which includes a carry flag.  However this is\n  not used for flow-of-control, but to enable mutliple precision arithmetic.\n- **Little endian**. The architecture is little-endian -- the least significant\n  byte of a word or double word is at the lowest address. The behavior for\n  instruction memory is that one word is fetched, since it may be a 16-bit\n  instruction.  If a second word is needed, then its fields are paired with the\n  first instructions to give larger values for each field.  This is done in\n  little-endian fashion, i.e. the field from the second instruction forms the\n  most significant bits of the combined field.\n- **No delay slots**. Early RISC designs introduced the concept of a delay slot\n  after branches. This avoided pipeline delays in branch processing.\n  Implementations can now avoid such pipeline delay, so like most modern\n  architectures, AAP does not have delay slots.\n- **NOP with argument for simulator control**. This idea is taken from OpenRISC.\n  The NOP opcode includes fields to specify a register and a constant.  These\n  can be used in both hardware and simulation to trigger side-effects.\n\n# Demo\n\n- **Screencast showing off the build system**: Like an actual video, but you\n  have to do a lot of reading?!\n\n  [![asciicast](https://asciinema.org/a/bjdyr19g4fvhxxzm3xt4dzk79.png)](https://asciinema.org/a/bjdyr19g4fvhxxzm3xt4dzk79)\n\n- **Gifcast showing off IRL usage**: A videocast that loops -- forever.\n\n  [![TODO FIXME](https://i.imgur.com/vPtJ1VV.jpg)](https://i.imgur.com/vPtJ1VV.jpg)\n\n# FAQ\n\nAnswers to the questions absolutely nobody has asked.\n\n- **Q**: _Why write this, what's the motivation?_\u003c/br\u003e\n  **A**: To learn more about digital hardware design. I didn't know Verilog or\n  anything about FPGAs/electronics. A simple CPUs seem like a rite-of-passage:\n  something real that you can use, but well explored. I had bought a Xilinx\n  FPGA (the Papilio One) years ago, but put off learning about mostly because\n  the software used to support modern FPGAs are absolutely *awful*. God awful.\n  \n  Thanks to tools like [Yosys][yosys] and [Project IceStorm][icestorm] for\n  Lattice iCE40 FPGAs, that's now changed -- it's possible to build *real*\n  designs with an open source toolchain, taking just a few megabytes of hardrive\n  space, that can synthesize and route designs that are competetive with\n  proprietary tools. It's a clean-room, best-approximation-reverse-engineering\n  effort -- but the usability and simplicity is so much better for a newcomer\n  that it's hard to grasp. And the FPGAs in question are very cheap. The value\n  of this is hard to overstate for people new to digital design.\n\n- **Q**: _Why choose the AAP? Why not RISC-V or something?_\u003c/br\u003e **A**: It's\n  quite simple, being designed as a reference 16-bit platform which you would\n  base your own tiny chips on. It's also relatively new, meaning there aren't\n  many implementations yet, so it seems like a good challenge to write a modular\n  implementation that can be tuned.\n\n  RISC-V is already quite well explored it seems - in the future if I attempt a\n  32-bit design, I'll likely attempt a specification of\n  the [J-Core](http://j-core.org/).\n\n- **Q**: _Can I use it in other designs?_\u003c/br\u003e\n  **A**: Yes. CLaSH can generate VHDL, Verilog or SystemVerilog, so hopefully\n  you can fit it into your flow however you like. The design doesn't use any\n  vendor-specific IP cores anywhere critical. However, Verilog is generally the\n  default target, as [Yosys][] is used to simplify and \"amalgamate\" the\n  resulting design for distribution, as a single `.v` file.\n\n- **Q**: _Why is it written in Haskell?_\u003c/br\u003e\n  **A**: Because Haskell is my programming language of choice and I have\n  extensive experience with it, and its implementation. CLaSH is essentially\n  Haskell with only very, very minor restrictions, so the choice made quite a\n  bit of sense to me.\n\n  At some level, I suppose you could just sum this point up as \"laziness\" (no\n  pun), and stubbornness since I'd rather stick with something I know -- but\n  it's essentially a question of the devil-you-know, vs the-devil-you-don't. I'm\n  much more comfortable with reading, and especially writing Haskell, than any\n  other HDLs. So I'm much more productive and can think much more clearly.\n\n# Building\n\nBuilding the design, running the tests and uploading to a board all depends on\nthe specific combination of tools and hardware you have available.\n\n(Simulation is always available in multiple forms, if you have no hardware\navailable. The open source [IceStorm Flow][icestorm] can be installed with no\nhassle or hardware, allowing you to run and test the full build process.)\n\n## Supported boards and synthesis flows\n\n[Yosys](http://www.clifford.at/yosys/) is used as a generic synthesis frontend,\nrun after the CLaSH compiler, that amalgamates and emits a monolithic,\nsimplified Verilog module containing the entire design. All flows -- no matter\nthe target, netlist or simulator -- first use Yosys to generate Verilog that is\nthen synthesized with the appropriate tools.\n\nLanguages for the given flows are classified by what the tools *natively*\nsupport, unless specified otherwise.\n\nThe following synthesis flows have been tested, or will hopefully be\nsupported/explored in time:\n\n- (**Lang Legend**: **V** = Verilog, **SV** = SystemVerilog, **HDL** = VHDL)\n\n| Flow | Description | Supported | Lang | Notes |\n| --- | --- | --- | --- | --- |\n| [IceStorm Flow][icestorm] | Open-source flow for iCE40 FPGAs. | :white_check_mark: **Full** | V/~~SV~~\u003csup\u003e1\u003c/sup\u003e/~~HD~~L\u003csup\u003e1\u003c/sup\u003e | Default flow and primary target. Fully automated. |\n| iCEcube2 | Official Lattice flow for iCE40 FPGAs. | :heavy_exclamation_mark: **Partial** | V/HDL | Secondary flow target, not automated.\u003csup\u003e2,3\u003c/sup\u003e Uses IceStorm for programming. |\n| WebPack ISE | Xilinx flow for Spartan FPGAs. | :x: **No** | V/HDL | |\n| Vivado | Xilinx flow for high-end Xilinx FPGAs | :x: **No** | V/SV/HDL | |\n| Quartus | Altera flow for Cyclone/etc FPGAs. | :x: **No** | V/SV/HDL | Preliminary Modelsim ASE simulation. |\n\n\u003csup\u003e1\u003c/sup\u003e Only available when Yosys is compiled\nwith [Verific](http://www.verific.com) support.\u003cbr/\u003e\n\u003csup\u003e2\u003c/sup\u003e Tested with Synplify Pro and Lattice Synthesis Engine (LSE) for\nnetlist synthesis. Active-HDL simulation is unsupported.\u003cbr/\u003e\n\u003csup\u003e3\u003c/sup\u003e Getting Synplify Pro working properly is a hellish nightmare of\npatching shell scripts. Good luck.\n\n[icestorm]: http://www.clifford.at/icestorm/\n\nThe following matrix lists the set of supported hardware and synthesis flows\nthat have been tested and are supported by the build system, or ones that I\ninevitably plan to try and support if possible (or if others can confirm\nsupport):\n\n- (**Flow Legend**: **ICE** = IceStorm Flow, **C2** = iCEcube2, **ISE** =\n  WebPack ISE, **VIV** = Vivado, **QR** = Quartus.)\n- (**Support Legend**: :white_check_mark: = Supported, :heavy_minus_sign: =\n  Partial, not automated, :heavy_exclamation_mark: = Untested, but should work\n  with some fiddling, :x: = Unsupported without a bit of work.)\n\n| Board | Chip | Flow | Support | Notes |\n| --- | --- | --- | --- | --- |\n| [iCE40-HX8K Breakout Board][8kbb] | iCE40-HX8K-CT256 | **ICE**, **C2** | :white_check_mark:, :heavy_minus_sign: | Default board; sitting on my desk. |\n| [iCE40-HX1K \"IceStick\"][icestick] | iCE40-HX1K-VQ144 | **ICE**, **C2** | :heavy_exclamation_mark:, :x: | |\n| [IcoBoard][icoboard] | iCE40-HX8K-CT256(?) | **ICE**, **C2** | :heavy_exclamation_mark:, :x: | |\n| [Go Board][goboard] | iCE40-HX1K-VQ100 | **ICE**, **C2** | :heavy_exclamation_mark:, :x: | |\n| [iCEblink40][iceblink] | iCE40-HX1K-VQ100 | **ICE**, **C2** | :heavy_exclamation_mark:, :x: | |\n| [Papilio One 500k][pp1_500k] | Spartan 3E XC3S500E | **ISE** | :x: | Need to dust off from my desk. |\n| [Basys 3][basys3] | Artix-7 XC7A35T-1CPG236C | **VIV** | :x: | |\n| [DE0-Nano SoC][de0nano] | Cyclone-V 5CSEMA4U23C6N | **QR** | :x: | No Altera kits on-hand. |\n\n[icestick]: http://www.latticesemi.com/icestick\n[8kbb]: http://www.latticesemi.com/Products/DevelopmentBoardsAndKits/iCE40HX8KBreakoutBoard.aspx\n[icoboard]: http://www.icoboard.org/\n[goboard]: https://www.nandland.com/goboard/introduction.html\n[iceblink]: http://www.latticesemi.com/iceblink40-hx1k\n[pp1_500k]: http://store.gadgetfactory.net/papilio-one-500k-spartan-3e-fpga-dev-board/\n[basys3]: http://store.digilentinc.com/basys-3-artix-7-fpga-trainer-board-recommended-for-introductory-users/\n[de0nano]: http://www.terasic.com.tw/cgi-bin/page/archive.pl?No=941\n\n## Environment setup\n\nThe build system and hardware design itself are both written in Haskell, so you\nwill need the Haskell and CLaSH compiler(s), on top of the needed synthesis\ntools, and the testing tools.\n\nFor the hardware design and build system, you need:\n\n  - GHC 7.10.3 (exactly)\n  - Cabal 1.24 or above (it **must** be version 1.24 or later!)\n  - The CLaSH compiler (via `cabal install clash-ghc`)\n\nFor synthesis, you need:\n\n  - icestorm -- \u003chttp://www.clifford.at/icestorm/\u003e\n  - yosys -- \u003chttp://www.clifford.at/yosys/\u003e\n  - arachne-pnr -- \u003chttps://github.com/cseed/arachne-pnr\u003e\n\nFor running the full testbench, you also need:\n\n  - Icarus Verilog -- \u003chttp://iverilog.icarus.com/\u003e\n\n## Configuring the build\n\nLook inside `cfg/build.cfg`, which is extensively documented with configuration\noptions for the build system. These values are primarily used to override the\nlocations to any needed tools, and configuring the synthesis and upload process\n(e.g. you must specify what board you plan on building for).\n\nRead the options in `cfg/build.cfg` for more. The default settings are\nappropriate for synthesis onto the [iCE40-HX8K Breakout Board][default-board].\n\nNote that the build system is very smart: if you modify `cfg/build.cfg`, by\nchanging some value for example, the build system will automatically detect\nthis, and re-run the affected rules that are touched by that option.\n\n[default-board]: http://www.latticesemi.com/Products/DevelopmentBoardsAndKits/iCE40HX8KBreakoutBoard.aspx\n\n## Do one stupid thing first\n\nDo this first, after you've run `cabal install clash-ghc`:\n\n```\n$ cd src/clash-extras \u0026\u0026 cabal install \u0026\u0026 cd ../..\n```\n\nThis will install a utility library that is used by both the AAP implementation,\nand the build system, when synthesizing designs for Lattice iCE40 FPGAs, along\nwith some other goodies for CLaSH. It needs to be installed into the user\npackage database directly, as the `clash` executable needs to be able to find\nthe `clash-extras` package when it compiles the design.\n\nThe need to do this manually is a short-term problem. In the future, the build\nsystem will do it automatically if needed (and further down the line, hopefully\nintegration and improvements to `cabal new-build` will allow this to be\ntransparent).\n\n## Compiler toolchain\n\nTODO FIXME\n\n## Running the build\n\nIf you have all of the necessary prerequisites, the following might work if\nyou're lucky:\n\n```\n$ ./do -j # -j means \"use as many processors as possible in parallel\"\n```\n\nThis will automatically compile the Shake build system when you run it for the\nfirst time. This uses `cabal new-build` (which is why you need `cabal-install`\n1.24 or above). Note that this may take a while, since `cabal` will have to\ndownload and install all the dependencies of the build system. Afterwords, the\nbuild will start instantaneously.\n\nYou may modify any of the source code to the AAP implementation, and rerun\n`./do`. It will always recompile what is necessary based on your changes.\n\nFurthermore, if you modify any of the build system source code, `./do` will\nautomatically re-compile the build system before continuing.\n\nYou may specify a target to be built directly, as an argument to `./do`. The\ndefault target (if no arguments are specified) builds the simulation\nexecutables, the FPGA bistream, and does a timing analysis.\n\nYou can generate a fancy `report.html` file detailing the steps the build system\ntook, with `./do --report`.\n\nRun `./do --help` for more build system options.\n\n### Build artifacts\n\nThe results of the build are under the `build/` directory. Some of\nthese results are:\n\n  - Binary results\n    - `build/claap.blif`: resulting design in BLIF netlist format, before\n      place-and-route.\n    - `build/claap.asc`: resulting design in IceStorm ASCII format, after\n      synthesis and place-and-route.\n    - `build/claap.bin`: FPGA binary, ready for upload.\n  - Synthesis results\n    - `build/claap-synth.v`: Single-file Verilog output from yosys, containing\n      the entire design as an optimized Verilog module. This has the reset and\n      clock attached to an onboard PLL, typically.\n    - `build/claap-simple.v`: Single-file Verilog output from yosys, containing\n      the entire design as an optimized Verilog module. The wires, etc are all\n      free, so this can be incorporated into other designs easily.\n  - Logs\n    - `build/synth.log`: Synthesis log.\n    - `build/pnr.log`: Place-and-route log.\n    - `build/timing.log`: Timing analysis results.\n\n### Cleaning up\n\n```\n$ ./do clean # or `rm -rf build/`\n```\n\n## Running the testbench\n\nTo run the full testbench:\n\n```\n$ ./do test\n```\n\nThis will:\n\n  - Run the CLaSH simulation, which is created by compiling the Haskell program\n    to an ordinary executable. This will run several tests, and exercise a\n    testbench that will also be compiled to Verilog.\n\n  - Run a simulation of the CLaSH compiler output with `iverilog`. The Verilog\n    source and Verilog testbench is generated by the CLaSH compiler\n    automatically.\n\n  - Run a timing analysis on the resulting design, and spit out the path delay\n    and max frequency analysis results. If `cfg/build.cfg` has been set up to\n    specify `ICETIME_CHECK_MHZ`, this will optionally ensure that the resulting\n    design can meet the specified timing requirement in megahertz. If the design\n    cannot meet the specified requirement, the test fails.\n\n## Uploading to your board\n\nIf you've specified everything correctly, you can attempt to set your house on\nfire by uploading the resulting design to your board, with the appropriate\nprogramming tool:\n\n```\n$ ./do upload\n```\n\nNote that the above example assumes your user account has permission (somehow)\nto upload the FPGA bitstream to the board. This typically involves directly\ninterfacing with a USB port device (requiring `write(2)`/`open(2)`\ncapabilities), so you may need `sudo` to upload.\n\nFor iCE40 boards, fixing this on Linux with `udev` is relatively\nstraightforward, allowing you to upload bitstream files with your unprivileged\nuser account. First, create a file `/etc/udev/rules.d/99-fpga-icestorm.rules`\nwith the contents:\n\n```\nATTRS{idVendor}==\"0403\", ATTRS{idProduct}==\"6010\", MODE=\"0660\", GROUP=\"plugdev\"\n```\n\nAdd yourself to the `plugdev` group. Log-out and log back in to reset your\nrunning session to have the proper group permissions.\n\nThis will cause `udev` to automatically assign group-write permissions to any\nLattice iCE40 FPGA that's plugged in, allowing the `plugdev` group to open/write\nto the device. This is specified as a custom user rule for `udev`, with priority\n99, meaning it will happen after all other rules (taking priority in case of\nconflict).\n\nWith this in place you should be able to simply plug in your device via USB and\nyour unprivileged user should be able to upload bitstream files.\n\n# Performance, timing, utilization\n\nTODO FIXME\n\n## Performance notes\n\n## Timing and utilization\n\n## Dhrystone\n\n# References\n\n- [EAP 13: AAP instruction specification][eap13]\n- [EAP 14: Verilog AAP implementation][eap14]\n\n[eap13]: http://www.embecosm.com/appnotes/ean13/ean13.html\n[eap14]: http://www.embecosm.com/appnotes/ean14/ean14.html\n\n# Join in\n\nBe sure to read the [contributing guidelines][contribute]. File bugs\nin the GitHub [issue tracker][].\n\nMaster [git repository][gh]:\n\n* `git clone https://github.com/thoughtpolice/claap`\n\n[contribute]: https://github.com/thoughtpolice/claap/blob/master/.github/CONTRIBUTING.md\n[issue tracker]: http://github.com/thoughtpolice/claap/issues\n[gh]: http://github.com/thoughtpolice/claap\n\n# Authors\n\nSee\n[AUTHORS.txt](https://github.com/thoughtpolice/claap/blob/master/AUTHORS.txt).\n\n# License\n\nBSD3. See\n[LICENSE.txt](https://github.com/thoughtpolice/claap/blob/master/LICENSE.txt)\nfor the exact terms of copyright and redistribution.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthoughtpolice%2Fclaap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthoughtpolice%2Fclaap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthoughtpolice%2Fclaap/lists"}