! VMware has ended active development of this project, this repository will no longer be updated.

FPGAs can exceed the performance of general-purpose CPUs by several orders of magnitude and offer dramatically lower cost and time to market than ASICs. While the benefits are substantial, programming an FPGA can be an extremely slow process. Trivial programs can take several minutes to compile using a traditional compiler, and complex designs can take hours or longer.

Cascade is a novel solution to this problem, the world's first just-in-time compiler for Verilog. Cascade executes code immediately in a software simulator, and performs compilation in the background. When compilation is finished, the code is moved into hardware, and from the user’s perspective it simply gets faster over time. Cascade's ability to move code back and forth between software and hardware also makes it the first platform to provide generic support for the execution of unsynthesizable Verilog from hardware. The effects are substantial. Cascade encourages more frequent compilation, reduces the time required for developers to produce working hardware designs, and transforms HDL development into something which closely resembes writing JavaScript or Python. It takes the first steps towards bridging the gap between programming software and programming hardware.

Much of the work which has gone into building Cascade has been documented in conference proceedings. A complete list of publications (hopefully with more to come) is below. Note however, that Cascade is under active development. In some cases, its implementation may have diverged what is described in these texts. The most up-to-date information on Cascade's implementation is always its source code.

• Just-in-Time Compilation for Verilog -- ASPLOS 2019

Recent Updates:

• 12/19 Cascade supports the ULX3S as a backend target.
• 11/19 Cascade uses Verilator as an intermediate compilation pass between software simulation and hardware.
• 10/19 Cascade provides experimental support for Xilinx FPGAs on Amazon F1 (release coming soon).
• 9/19 Cascade can be linked into C++ projects as a library. This allows Cacade to target itself as a backend target.
• 7/19 Cascade supports unsynthesizable file I/O primitives from hardware.
• 5/19 Cascade supports the DE10 Nano as a backend target.

Index

0. Dependencies
1. Building Cascade
2. Using Cascade
   1. Command Line Interface
   2. As a Library
3. Environments
   1. Software Backend
   2. Hardware Backends
      1. DE10 Nano
      2. ULX3S
   3. JIT Compilation
4. Support for Synthesizable Verilog
5. Support for Unsynthesizable Verilog
6. Standard Library
7. Target-Specific Components
8. Adding Support for New Backends
9. FAQ

Dependencies

Cascade should build successfully on OSX and most Linux distributions.

Building Cascade

1. Clone this repository

   $ git clone https://github.com/vmware/cascade

2. Run the setup script

$ cd cascade
$ ./setup

The setup script should guide you through installing dependencies, as well as configuring, building and testing Cascade.

Using Cascade

Command Line Interface

Start Cascade by typing

$ cascade

This will place you in a Read-Evaluate-Print-Loop (REPL). Code which is typed here is appended to the source of the (initially empty) top-level (root) module and evaluated immediately. Try defining a wire.

>>> wire x;

The Verilog specification requires that code inside of initial blocks is executed exactly once when a program begins executing. Because Cascade is a dynamic environment, we generalize that specification: code inside of initial blocks is executed exactly once immediately after it is compiled. Try printing the value of the wire you just defined. Cascade uses a two-value model for signals. Unknown logic values (X) are set to zero, and high-impedence values (Z) are assigned non-deterministic values.

>>> initial $display(x);
>>> 0

Now try printing a variable which hasn't been defined.

>>> initial $display(y);
>>> Typechecker Error:
>>>  > In final line of user input:
>>>    Referenece to unresolved identifier: y

Anything you enter into the REPL is lexed, parsed, type-checked, and compiled. If any part of this process fails, Cascade will produce an error message and the remainder of your text will be ignored. If you type multiple statements, anything which compiles successfully before the error is encountered cannot be undone. Below, x and y are declared successfully, but the redeclaration of x produces an error.

>>> wire x,y,x;
>>> Typechecker Error:
>>>  > In final line of user input:
>>>    A variable named x already appears in this scope.
>>>    Previous declaration appears in previous user input.
>>> initial $display(y);
>>> 0

You can declare and instantiate modules from the REPL as well. Note however, that declarations will be type-checked in the global scope. Variables which you may have declared in the root module will not be visible here. It isn't until a module is instantiated that it can access program state.

>>> module Foo(
>>>   input wire x,
>>>   output wire y 
>>> );
>>>   assign y = x;
>>> endmodule
>>> wire q,r;
>>> Foo f(q,r);

If you don't want to type your entire program into the REPL you can use the include statement, where path/ is assumed to be relative to your current working directory.

>>> `include "path/to/file.v"

If you'd like to use additional search paths, you can start Cascade using the -I flag and provide a list of semicolon-separated alternatives. Cascade will try each of these paths as a prefix, in order, until it finds a match.

$ cascade -I path/to/dir1:path/to/dir2

Alternately, you can start Cascade with the -e flag and the name of a file to include.

$ cascade -e path/to/file.v

Finally, Cascade will stop running whenever a program invokes the $finish task.

>>> initial $finish;
Goodbye!

You can also force a shutdown by typing Ctrl-C or Ctrl-D.

>>> module Foo(); wir... I give up... arg... ^C

As a Library

Cascade can also be called directly from C++ code. Cascade's command line interface is a thin-wrapper around a small set of functions. A minimal example is shown below. Further dicussion of the concepts in this example appears in subsequent sections of this README.

#include <cassert>
#include <iostream>
#include <sstream>
#include <cascade.h>

using namespace cascade;
using namespace std;

int main() {
    // Create an instance of Cascade. Cascade is thread-safe. Multiple instances
    // may share the same address space.
    Cascade cascade;

    // Configuration options. These methods should all be called before
    // cascade starts running.
    cascade.set_include_dirs(...);
    cascade.set_enable_inlining(...);
    cascade.set_open_loop_target(...);
    cascade.set_quartus_server(...);
    cascade.set_profile_interval(...);

    // Cascade exposes its six i/o streams (the standard STDIN, STDOUT, and
    // STDERR, along with  three additional STDWARN, STDINFO, STDLOG) as
    // C++ streambufs. These are initially mapped to nullptr. Changes to this
    // mapping should also be made before cascade starts running.
    cascade.set_stdin(cin.rdbuf());
    cascade.set_stdout(cout.rdbuf());
    cascade.set_stderr(cerr.rdbuf());
    cascade.set_stdwarn(cerr.rdbuf());
    cascade.set_stdinfo(clog.rdbuf());
    cascade.set_stdlog(...);

    // Start cascade. This method returns immediately.
    cascade.run();

    // Cascade will run until the user's program invokes the $finish() task or the 
    // user requests that it stop running. The request_stop() method returns immediately. 
    // The wait_for_stop() method will block until either of the above conditions
    // is satisified.
    cascade.request_stop();
    cascade.wait_for_stop();

    // Stopping cascade only pauses its execution. All previous state is retained.
    // To continue running, call run() again.
    cascade.run();

    // Cascade is a c++ ostream. While it is running, any text provided to it
    // via the << operator, will be eval'ed. Since every program must begin with an
    // march file, you can use an include statement to eval one.
    cascade << "`include \"path/to/march.v\"";

    // Because cascade runs asynchronously, it has no way of knowing when user input
    // has ended. The user can force this by using the flush() method, or passing 
    // cascade a c++ endl. Be careful with using endl to separate multi-line inputs.
    // This may cause cascade to prematurely evaluate user input. When in doubt, prefer '\n'.
    cascade.flush(); 
    cascade << endl;

    // The results of the eval statements which have taken place since the previous
    // flush are available through ostream status bits. Cascade is placed in
    // in the eof state when it encounters an eof character, and in the bad state when
    // an eval results in a parse or type error. Because cascade runs asynchronously, the 
    // only way to make sure an eval has run to completion is to request a stop. The standard
    // mechanism for clearing an ostream's state bits is to use the clear() method.

    assert(!cascade.bad()); // Not guaranteed to see the result of the previous eval.
    cascade.stop_now(); // Syntactic sugar for request_stop(); wait_for_stop();
    assert(!cascade.bad()); // Both guaranteed to see the result of the previous eval.
    assert(!cascade.eof()); 
    cascade.clear(); // Clears eof and bad bits.

    // While cascade is stopped, it is safe to replace its rdbuf. For example:
    stringstream ss("wire x; initial $display(\"Hello, world!\");");
    cascade.rdbuf(ss.rdbuf());
    cascade.run();

    // Note however, that most c++ implementations assign non-standard semantics to
    // cin. It's safe to switch cascade's rdbuf to cin. But once this is done, it is
    // no longer safe to change it again.
    cascade.stop_now();
    cascade.rdbuf(cin.rdbuf());
    cascade.rdbuf(ss.rdbuf()); // UNDEFINED!
    cascade.run();

    // Block until the user's program invokes the $finish() task.
    cascade.wait_for_stop();

    return 0;
}

To build a program that uses Cascade as a library, statically link against libcascade. If you installed cascade to a directory other than /usr/local/ you'll need to provide alternate values for the -I and -L flags.

$ g++ --std=c++17 -I/usr/local/include/cascade my_program.cc -lcascade

Environments

Software Backend

By default, Cascade runs in software. You can invoke this behavior explicitly using the --sw flag.

$ cascade --march sw

This environment declares the following module and instantiates it into the top-level module for you:

module Clock(
  output wire val
);
endmodule

Clock clock;

This module represents the global clock. Its value toggles between zero and one every cycle. Try typing the following (and remember that you can type Ctrl-C to quit):

>>> always @(clock.val) $display(clock.val);
>>> 0
>>> 1
>>> 0
>>> 1
>>> ...

This global clock can be used to implement sequential circuits, such as the barrel shifter shown below.

>>> module BShift(
>>>   input wire clk,
>>>   output reg[7:0] val
>>> );
>>>   always @(posedge clk) begin
>>>     val <= (val == 8'h80) ? 8'h01 : (val << 1);
>>>   end
>>> endmodule
>>> wire[7:0] x;
>>> BShift bs(clock.val, x);

Compared to a traditional compiler which assumes a fixed clock rate, Cascade's clock is virtual: the amount of time between ticks can vary from one cycle to the next, and is a function of both how large your program and is and how often and how much I/O it performs. This abstraction is the key mechanism by which Cascade is able to move programs between software and hardware without involving the user.

Up until this point the code we've looked at has been entirely compute-based. However most hardware programs involve the use of I/O peripherals. Before we get into real hardware, first try running Cascade's virtual software FPGA.

$ sw_fpga

Cascade's virtual FPGA provides an ncurses GUI with four buttons, one reset, and eight leds. You can toggle the buttons using the 1 2 3 4 keys, toggle the reset using the r key, and shut down the virtual FPGA by typing q. Cascade's software backend will automatically detect the virtual FPGA and expose its peripherals as modules which are implicitly declared and instantiated in the top-level module:

module Pad(
  output wire[3:0] val
);
endmodule
Pad pad();

module Reset(
  output wire val
);
endmodule
Reset reset();

module Led(
  output wire[7:0] val
);
endmodule
Led led();

Try writing a simple program that connects the pads to the leds.

>>> assign led.val = pad.val;

Toggling the pads should now change the values of the leds for as long as Cascade is running.

Hardware Backends

Cascade currently provides support for two hardware backends: the Terasic DE10 Nano SoC and the ULX3S. When Cascade is run on either of these targets, instead of mapping compute and leds onto virtual components, it can map them directly onto real hardware.

DE10 Nano

Before using the de10 backend you'll first need to install Intel's Quartus Lite IDE on a network-accessible 64-bit Linux machine. You'll also need to run Cascade's compilation server on that machine.

$ quartus_server --path <quartus/install/dir> --port 9900

Alternatively, you can use Quartus Lite IDE installed on a remote host:

$ quartus_server --tunnel-command <command/like/ssh> --path <quartus/install/dir> --port 9900

Next you'll need an SD card image for your DE10 with a valid installation of Cascade. Cascade can generate this image for you automatically or you can download a prebuilt image here (todo). Reboot your DE10 using this image and run Cascade as usual (but on the DE10, use sudo).

$ cd cascade
$ sudo cascade --march de10 --quartus_host <64-bit Linux IP> --quartus_port <64-bit Linux port>

Assuming Cascade is able to successfully connect to the FPGA fabric, you will be presented with a similar environment to the one you encountered when using the software backend. The only difference is that instead of a Reset module, Cascade will implicitly declare the following module, which represents the DE10's Arduino header.

module GPIO(
  input wire[7:0] val
);
endmodule
GPIO gpio();

Try repeating the example from the previous section and watch real buttons toggle real leds.

ULX3S

Cascade supports the ULX3S using the entirely open source Yosys->NextPNR->ujprog toolchain. Before getting started, you'll need to follow the directions here for installing Yosys and NextPNR, and here for installing ujprog. Make sure that all components are installed to the standard /usr/local directory tree.

Next, you should be able to run Cascade as usual.

$ cascade --march ulx3s

Cascade does not currently support any of the I/O peripherals on the ULX3s, but it can target its reprogrammable fabric to improve virtual clock frequency for most applications.

JIT Compilation

If you'd like more information on how Cascade transitions code between software and hardware, trying using the --enable_info flag. This will cause Cascade to print status updates to the REPL whenever part of your program begins execution in a new context.

$ cascade --enable_info

In general, you can expect your virtual clock frequency to increase as more and more of your logic transitions to hardware. Providing the --profile <n> flag will cause Cascade to periodically (every