Skip to content

Latest commit

 

History

History
215 lines (132 loc) · 6.13 KB

Tutorial.md

File metadata and controls

215 lines (132 loc) · 6.13 KB

RAVEN Tutorial

Welcome to the RAVEN platform tutorial — an introductory guide to the main features and workflow of the tool.

1. Introduction

RAVEN combines an IDE and a simulator to make learning the RISC‑V architecture easier. You can write, assemble, and run assembly code while observing in real time the behavior of memory, registers, and the decoding of each instruction.

2. Interface Structure

The interface is organized into tabs that mirror the development flow:

  1. Editor — write and assemble code
  2. Run (Simulation) — step execution; view memory and registers
  3. Cache — inspect cache stats and tune cache configuration
  4. Docs — instruction reference

3. Tab: Text Editor

EditorSection

The Editor tab is the starting point. Here you can write, assemble, import, and export RISC‑V assembly code.

Key Features

  • Build Status: shown in the Editor Status section (image [1]), indicating the result of assembly.
  • Import and Export:
    • Text files: .asm and .fas
    • Binaries: generated by RAVEN (.bin)
  • Build Shortcut: Ctrl + R assembles the code and shows the status.
EditorSection2

Code Structure

You may write instructions directly without declaring sections. When you need data, use:

.section .data   ; or just .data

to delimit the data region, and:

.section .text   ; or just .text

to delimit the instruction region.

4. Tab: Run (Simulation)

The Run tab is dedicated to execution and detailed inspection of the program. You can track memory, registers, and the binary decoding of instructions.

Each executed instruction presents:

  • Field Map: a binary map of each instruction field
  • Parsed Fields: decoded field values
  • Console: allows I/O interaction
image

Resizing Windows

You can freely resize windows in this tab. Move the cursor to a window border (indicated by an arrow). If it turns yellow, resizing is available. Click, hold, and drag:

  • Console: vertical (up/down)
  • Instruction Memory: horizontal (left/right)

WindowsTerminal_l4T0sBIA2c

Run Controls

Control execution and how memory is decoded using toggles:

  • State: switch between RUN and PAUSE
  • View: switch between Registers and RAM

WindowsTerminal_2La84UZiCS

Memory Window

The left window in Run shows memory and registers; both can be scrolled with the mouse wheel. Switch the view with the View button in Run Controls.

Data interpretation modes:

  • Hex: hexadecimal
  • Dec: decimal
  • STR: ASCII text

Decimal Options

In Dec mode you can toggle between:

  • SGN: signed numbers
  • UNS: unsigned numbers

View RAM

In RAM view you can jump to areas of interest such as:

  • .data: where .data values reside
  • Stack: the stack region pointed to by SP (stack pointer)

You can also change address grouping to 4B, 2B, or 1B.

WindowsTerminal_YF5tCEQbFG

Instruction Memory

This window shows the progress of the PC (Program Counter). The yellow band marks the instruction currently at PC. Instruction Details, Field Map, and Parsed Fields reflect it in real time.

Instruction Hover

When you hover an instruction, a blue bar appears next to it. Clicking moves the PC to that instruction. The hovered instruction defines what is shown in Instruction Details, Field Map, and Parsed Fields.

WindowsTerminal_tv0ar7PnGQ

Manual Step

To inspect programs in detail, you can advance the PC manually. With the simulation paused, press S to step to the next instruction.

WindowsTerminal_0kLnfl2qIZ

5. Tab: Cache (Simulation)

The Cache tab helps you visualize (and tweak) a simple I-cache + D-cache model.

Cache → Stats

  • Live hit rate gauges and a history chart
  • Extra derived metrics such as miss rate, line fills, avg cycles/access, and RAM R/W bytes
  • Top Miss PCs (I-Cache): which fetch PCs are responsible for most I-cache misses

Controls:

  • Reset clears cache stats
  • Pause/Resume pauses/resumes the simulation (cache stats stop updating while paused)
  • Scope toggles let you focus on I-cache, D-cache, or both

Cache → Config

You can edit cache parameters (size, line size, associativity) and policies, then apply them at runtime.

For full details, see cache.md.

6. Performing I/O

RAVEN aims to be straightforward while remaining faithful to RISC‑V behavior. To reduce boilerplate and keep code readable, it provides pseudo‑instructions for common tasks — especially I/O and stack handling.

While all pseudos are documented in format.md, this chapter shows a practical example demonstrating I/O interaction and how these abstractions help development.

The code below uses I/O pseudos (printStr, readWord, print, etc.) to read two numbers, add them, and print a formatted result.

.data 
 start: .asciz "Enter two numbers"
 theSum: .asciz "The sum of "
 with: .asciz " with "
 is: .asciz " is "
 void: .asciz ""
number1: .word 0
number2: .word 0

.text 
printStrLn start
readWord number1
readWord number2
printStrLn void
call calculate

printStr theSum
print s1
printStr with
print s2
printStr is
print s0

li a0, 0
li a7, 93      # syscall: exit
ecall


calculate:
    la t0, number1
    lw t1,0(t0)
    la t2,number2
    lw t3,0(t2)
    add s0,t1,t3
    mv s1,t1
    mv s2,t3
    ret

Execution example:

WindowsTerminal_e0XEHNKWAu