Home

Awesome

WARP-V logo

The open-source RISC-V core IP you can shape to your needs!

Overview

WARP-V is an open-source CPU core generator written in TL-Verilog with support for RISC-V and MIPS I. It is a demonstration and exploration vehicle for the flexibility that is possible using the emerging "transaction-level design" methodology. It can implement a single-stage, low-power microcontroller or a mid-range 7-stage CPU. Even the instruction-set architectures (ISAs) is configurable. WARP-V is an evolving library of CPU components as well as various compositions of them. It is driven by a community interested in transforming the silicon industry through open-source hardware and revolutionary design methodology.

WARP-V includes CPU core logic only with no current support for virtual memory, caches, or IOs. RISC-V implementations are formally verified using open-source tools in continuous integration testing. They have been formally verified also by Axiomise.

Links

Explore WARP-V

We built a <a href="https://warp-v.org">configurator</a>, so you can quickly build a CPU to suit your needs!

Publications

Collaboration

Installation

In a clean directory:

git clone https://github.com/stevehoover/warp-v.git
cd warp-v
./init

Build with Fusesoc

git clone https://github.com/shariethernet/my_edalize.git

cd edalize

git checkout main

pip3 install --user -r dev-requirements.txt

pre-commit install

pip3 install --user -e .

pip install fusesoc

fusesoc library add warpv .

fusesoc run --target=sandpiper warpv

Warp-v can be configured according to your requirement by setting the mxdef: in warp-v.core

Note: In the the .core files use [] wherever you intend to use (). As Fusesoc parsers donot support (), the [] acts as a place holder and gets replaced by () later on.

Features

Revolutionary Modeling Methodology

As an exploration vehicle for capabilities that are not yet defined in the <a href="http://tl-x.org/" target="_blank" target="_blank" atom_fix="_">TL-Verilog language spec</a>, WARP-V intentionally pushes the limits of code construction using an M4-based flow. While TL-Verilog documentation and tools are fairly mature, the M4 layer intended only for research.an undocumented proof-of-concept framework (even when old-school Verilog features might suffice). If you've come here to learn about TL-Verilog for RISC-V design, you'd be better served to study the cores developed in the Microprocessor for You in Thirty Hours Workshop.

WARP-V uses bleeding-edge modeling methodology that provides an unprecedented level of flexibility without sacrificing gate-level control. To understand WARP-V and how to utilize it, it helps to first gain an appreciation for this methodology, which involves two layers:

TL-Verilog

Transaction-Level Verilog extends Verilog/SystemVerilog with constructs for pipelines, transactions, etc. This provides a convenient modeling framework for parameterization at a higher level, but without sacrificing gate-level control. You can learn more about TL-Verilog at <a href="http://www.makerchip.com/" target="_blank" atom_fix="_">makerchip.com</a>.

Code Construction with M4

Code construction techniques for TL-Verilog are an active area of research. Before native implementation, code construction is being explored through the use of a macro preprocessor, <a href="https://www.gnu.org/software/m4/" target="_blank" atom_fix="_">M4</a> (plus a bit of Perl). Macro preprocessing is used in WARP-V to enable a single definition of the instruction set to be used to generate:

Logic related to replay and register bypass is generated based on CPU pipeline configuration.

There are simple uses of M4 that are easy to follow, such as including library files, defining constants, and instantiating macros. M4 features are supported in the Makerchip IDE as a short-term solution with some nice features to help with these use models. But M4 use in WARP-V goes way beyond these scenarios, intentionally pushing the limits of code construction. A small amount of code does a lot, but it is very messy, undocumented, and extremely difficult to debug. So it is important to give careful consideration to your intended use of WARP-V.

More Detail

You can learn more about the WARP-V design methodology in <a href="http://www.makerchip.com/module/pane/DAC2018_WARP-V_Presentation.pdf" target="_blank" target="_blank" atom_fix="_">these slides</a>, presented at the Design Automation Conference in June 2018. Below is a corresponding poster.

DAC 2018 Poster

<a name="use"></a>

Ways to Use WARP-V -- Overview

Configuring WARP-V

High-level parameters are defined toward the top of the WARP-V file. You can modify parameters and compile from the command line, but it is easier to follow compilation steps and debug problems using the IDE at <a href="http://www.makerchip.com/" target="_blank" atom_fix="_">makerchip.com</a> as described below. There is no better guide for understanding parameters at this point than code comments.

Tweaking the uArch

Since M4 macro-preprocessing is not for the faint of heart, once you've got a CPU that's close to what you want, you can take the generated code as source and go from there. Ideally, that would mean using the TL-Verilog as source, since you still get a great deal of flexibility at that level, but if you are stuck in the past, you can start with the Verilog or SystemVerilog.

Modifying the ISA

Constructing an ISA from scratch would require heavy use of M4 and could be a tall order at this point. Small variations of RISC-V, however, are more feasible by making small adjustments to parameterization.

RISC-V Infrastructure

For RISC-V development (even if you are developing your own RISC-V core without using WARP-V itself) this repository has some useful infrastructure. It supports formal verification using <a href="https://github.com/cliffordwolf/riscv-formal" target="_blank" target="_blank" atom_fix="_">riscv-formal</a> run in continuous integration testing. So, you always know if your core is compliant.

In the Cloud

WARP-V is implemented on FPGAs in the cloud using the <a href="https://github.com/stevehoover/1st-CLaaS" target="_blank" target="_blank" atom_fix="_">1st CLaaS</a> (custom logic as a service) framework. You can implement your own customized WARP-V on FPGAs in the cloud, too!

Help

You can find help in the <a href="https://gitter.im/librecores/warp-v" target="_blank" atom_fix="_">LibreCores WARP-V Gitter Chat Room</a>. You might find commercial assistance there as well.

<a name="makerchip"></a>

Exploring WARP-V in Makerchip

A few pointers for exploring WARP-V in Makerchip:

Contributing

Keep in mind that WARP-V is a horrible starting point for learning TL-Verilog because of its high degree of configurability using M5. If you are interested in microarchitectural contributions, learn TL-Verilog first at <a href="http://www.makerchip.com/" target="_blank" atom_fix="_">makerchip.com</a>.

With a clear understanding of where to tread, you can navigate WARP-V and contribute successfully. WARP-V is a library with plenty of room to grow to cover a more complete spectrum of CPU microarchitecture. Be aware, however, that working with CPU microarchitecture means walking in a minefield of patents. Work with the community to define your contributions.

Work in a fork and submit push requests that have passed continuous integration (CI) testing (below). Your work is much more likely to be accepted if it is aligned with the community and doesn't risk patent infringement.

Share your intentions in the TL-Verilog Slack Workspace. We'll help you find an appropriate way you can help out.

<a name="formal"></a>

Formal Verification

WARP-V RISC-V implementations are verified using the <a href="https://github.com/cliffordwolf/riscv-formal" target="_blank" target="_blank" atom_fix="_">riscv-formal</a> open-source formal verification framework. Everything for formal verification is in the formal directory. See the <a href="https://github.com/stevehoover/warp-v/tree/master/formal" target="_blank" target="_blank" atom_fix="_">README.md</a> file there.

formal/Makefile uses SandPiper-SaaS.

(For other ISAs, <a href="https://upscale.stanford.edu/" target="_blank" target="_blank" atom_fix="_">Upscale</a> might be a good direction for future work.)

RISC-V WARP-V cores have also been formally verified by Axiomise with some issues outstanding.

<a name="ci"></a>

CI

<a href="https://travis-ci.com/" target="_blank" atom_fix="_">Travis-CI</a> was used for continuous integration testing: <a href="https://travis-ci.com/stevehoover/warp-v" target="_blank" target="_blank" atom_fix="_">WARP-V Travis CI</a>. CI ran formal verification tests. Due to the introduction of fees, CI has been disabled and currently has not been successfully restored elsewhere. So, prior to merging with the main/master branch, run formal verification locally.

CI Environment

CI uses the formal/make_env.sh script to built the necessary tools from source. The result of this build is cached between builds (per branch) using a <a href="https://docs.travis-ci.com/user/caching" target="_blank" target="_blank" atom_fix="_">caching feature of Travis-CI</a>. Caching is applied blindly, without regard to the availability of newer sources. CI scripts will check the latest sources against the ones from the cache and report differences near the end of the log. The cache can be cleared manually from the build page. Look under "More options" (upper-right).

CI Debug

<a href="https://docs.travis-ci.com/user/running-build-in-debug-mode" target="_blank" target="_blank" atom_fix="_">Debugging Travis-CI failures</a> can be awkward. To simplify things, if a formal check fails, CI scripts attempt to upload the failure traces using https://transfer.sh/. Look for messages near the end of the log file containing links to the uploaded traces for download and debug.

Data

Implementation

TODO: Add implementation data here.

Retiming Experiments

We utilized the pipeline flexibility of TL-Verilog and WARP-V's pipeline parameterization to experiment with Vivado's ability to retime logic optimally. This showed that it is not necessary to precisely partition the CPU pipeline logic among pipeline stages in order to get good quality results. However, when tools must retime logic, runtime can be significantly impacted. Here is more detail.

Known Hardware Implementations