Skip to content
A graphical 5-stage RISC-V pipeline simulator & assembly editor
Branch: master
Clone or download
mortbopet Merge pull request #36 from TheThirdOne/unicode-fix
Make print_string support UTF-8
Latest commit 34c46a3 May 22, 2019

README.md

Ripes

Build Status

Ripes is a graphical 5-stage processor pipeline simulator and assembly code editor built for the RISC-V instruction set architecture, suitable for teaching how assembly level code is executed on a classic pipelined architecture. Ripes is especially suitable for illustrating how concepts such as forwarding and stalling works, giving a visual representation of both cases.

Features

  • Simulator:
    • 5-stage graphical pipeline simulator with visualization for multiplexer input selection, register write/enable signals and more.
    • Stage information: Current stage instructions are displayed above each stage, as well as in the instruction memory view
    • Breakpoint setting
    • Supports RISC-V assembly files & RISC-V binary files (extracted .text segments) - supported instructions are the RV32I Base Instruction Set as well as RV32M Standard Extension.
  • Memory:
    • Display type selection for various display formats (Hex, Decimal, ...)
    • Memory view with features such as scrolling adress saving and adress jumping
  • Editor:
    • Syntax highlighting and syntax error information
    • Real-time assembler for side-by-side comparison of assembly code and (disassembled) binary code

Contributing

Currently, Ripes features a single processor model - a 5 stage pipeline. However, in learning about computer architecture it may be valuable to have access to both less and more complex processor models.
A future goal for Ripes is to contain processor models such as the following:

  • Single-cycle
  • 2/3 stage pipeline
  • 5 stage pipeline without forwarding/hazard detection
  • 5 stage pipeline with forwarding/hazard detection
  • 5 stage pipeline(s) with varying placements of branching logic

However, describing all of these models with method of implementation currently used in Ripes would be highly tedious.

Instead, VSRTL was created. VSRTL is intended to be a collection of libraries and applications for visualizing simulations of digital circuits. VSRTL is currently in active development, and when mature, may be used to describe an arbitrary number of processor models for Ripes.
VSRTL is in active development and looking for developers - if this sounds interesting, check out the documentation or current issues for further info.

Downloading & Installation

Prebuilt applications are available for Linux, Windows & Mac/OSX. No installation is required - all required libraries are packaged with the compiled executable - these are available at the Releases page.
It is recommended to use the continuous releases, since they contain all of the most-recent bug-fixes.

Linux

Releases for Linux are distributed in the AppImage format. To run an AppImage:

  • Run chmod a+x on the AppImage file
  • Run the file! The AppImage for Linux should be compatible with most Linux distributions.

Windows

For Windows, the C++ runtime library must be available (if not, a msvcp140.dll error will be produced). You most likely already have this installed, but if this is not the case, you download it here.

Mac/OSX

Please note that the Mac/OSX is mostly untested and as such, there may be various visual glitches as well as performance issues.

Usage

The Ripes wiki contains various pages relating to writing RISC-V assembly code, as well as a list of the supported simulator features in terms of assembler directives etc.
To simulate C/C++ code in Ripes, Matt Godbolt's Compiler Explorer is a fast and easy-to-use web-based tool for generating RISC-V assembly code from C/C++. With minor modifications, the output from Compiler Explorer can be inserted into Ripes and simulated. For instructions on how to run code generated by Compiler Explorer, refer to this wiki page.

Editor

Get started by selecting one of the assembly examples through File->Load Example->assembly. In the Editor tab, you should now see that some RISC-V assembly code is present in the left view. Try changing some values or adding more instructions - you should see that the right side will change accordingly. By default, this view shows the disassembled version of the binary instructions that the left view has been assembled into. If you want to view the raw binary information, select Binary as View mode.

Processor

Once no syntax errors have been found in your assembly code, your code will automatically be assembled and loaded into the simulator. Switching to the Processor tab, you'll be greeted by a datapath picturing a classic 5-stage RISC pipeline architecture. Note that a Control component nor most control signals aren't included in the view. This descision has been made to reduce clutter. All control signals are generated in the ID (Instruction decode) stage, and are propagated through the stage-separating registers accordingly.

Besides the datapath, this tab contains the following elements:

  • Simulator control:
    • (1) Run will run the program until a breakpoint is encountered or execution is finished. This will postpone updating the visualized datapath until the break is encountered.
    • (2) Autostepping will automatically step through the program with a speed determined by the execution speed slider (5).
    • (3) Step is equal to activating the clock signal in the circuit. This will clock next-state signals into the registers, and new signals are calculated (propagate through the circuit)
    • (4) Reset resets the simulator, resetting all stages and setting the program counter to point to the first instruction
  • (6) Display all signal values will show the underlying output signals for most signals in the datapath
  • (7) Pipeline table: see below
  • (8) Various buttons are available for zooming & expanding the datapath view
  • (9) Registers is a view of the value of all registers in the processor, with highlighting for the most-recently used register
  • (10) Instruction memory: A view of the disassembled instructions that are currently loaded in the processor. This view displays which instructions are present in each pipeline stage, as well as breakpoint setting functionality Furthermore, the following options are available:

Pipelining table

will display a pop-up window with the stage information for the current program. The program must be run to propagate the chart. The pipeline table can be copied and pasted to spreadsheets.

Memory

Selecting the Memory tab will show you three different views:

  • Registers - similar to the view presented in the processor tab
  • A memory view, where all parts of the program memory can be inspected. To navigate, one can use the scroll view or select one of the predefined destinations (or to a specific address) via the Go to combobox. A label for an address can be saved for future use, via. the Save address button.
  • A list of the most recent memory accesses. Selecting an entry and pressing Go to selected address sets the right side memory view to center at the address for the given entry

Building

Since Ripes is built using pure C++ and Qt, all platforms that support Qt should be able to build and run the app. Ripes contains no external dependencies and (Assuming you have a Qt environment in your PATH) can be built by the following commands:

Unix:               Windows:
cd Ripes/           cd Ripes/
qmake               qmake.exe
make                jom.exe

Download Qt for Open Source development at https://www.qt.io/download. Using the Qt installer, only the prebuilt components for your chosen compiler needs to be selected.


Icons kindly provided by Flaticon authors: Smashicons, Freepik, Vectors Market & Pixel Buddha.

You can’t perform that action at this time.