OSCPU NutShell: RISC-V SoC Setup and FPGA Guide

What NutShell Solves for RISC-V Learners

NutShell addresses the gap between studying isolated processor concepts and assembling a system capable of executing software. The README identifies it as a processor developed by OSCPU, the Open Source Chip Project by University, and says that it supports riscv64/32. Its stated goals include booting Linux and Debian and taping out a chip. The primary audience is students and engineers who want to study Chisel-generated processor hardware, system integration, software loading, and FPGA deployment.

The repository is an educational SoC, not a hosted service or ordinary application library. Its main output is hardware. Based on the repository layout, Scala sources under `src/main/scala` feed a generation process that produces Verilog, while `fpga` contains board definitions, boot material, shared HDL, and a Vivado wrapper. That structure makes the project useful to readers who want to follow a design from processor description through generated RTL and, when appropriate, a programmable board.

NutShell originated as a fork of NOOP, an educational RV32 SoC from Nanjing University. According to the README, OSCPU started the separate NutShell project on 2019-08-27 and sought to enhance the educational design into a functional RV64 SoC. Its history is visible in the source and commit names, which can otherwise make the repository look more complicated than the README suggests.

How NutShell Generates Verilog with Mill

The documented hardware generation path starts with Mill. After installing `mill`, the README instructs users to run `make`, which produces `build/TopMain.v`. The Makefile identifies Scala files in `src/main/scala` and test files in `src/test/scala`, then invokes a Mill generator entry point. Its output is post-processed and stored under `build/rtl` before the expected top-level file is placed at `build/TopMain.v`.

Two selections shape generation. `BOARD` defaults to `sim`, and the Makefile lists `pynq` and `axu3cg` as examples. `CORE` defaults to `inorder`, with `ooo` and `embedded` also listed as possible values. Board selection also affects the generated top: `sim` and `fpgadiff` use `SimTop`, while other values use `Top`. The Makefile passes these selections into the generator and enables split Verilog output.

This gives users a clear source-to-RTL flow. Chisel descriptions written in Scala are processed by the Mill-based generator, the result becomes Verilog, and downstream simulation or FPGA tooling consumes the generated files. The README does not expose a detailed configurable cache interface, branch predictor controls, memory timing model, or microarchitecture selection guide. It therefore supports a clear account of the build mechanism, but not a complete explanation of every design option.

Installing Mill and Running the First Simulation

The README gives the installation prerequisite but does not provide a NutShell-specific package installation command. It says to install `mill` and refers to the Mill manual. Once Mill is available, the repository Makefile supplies the generation and simulation commands. The following sequence is the shortest documented first use: generate Verilog, then launch the prepared Linux image.

make
make emu

The first command invokes the default Verilog target and is expected to create `build/TopMain.v`. The second launches the simulation path. The Makefile defines `IMAGE` as `ready-to-run/linux.bin`, so the default run uses the repository's supplied Linux kernel image. The README does not state the exact prompt, runtime, or completion transcript, so the expected result is a launched emulator rather than a documented application output.

To use another image, pass its filename through the documented `IMAGE` variable. The repository includes a `ready-to-run` directory containing examples, although the README does not enumerate every image or explain which workloads each one represents. The reader should expect to confirm that the selected file matches the simulation's memory and startup assumptions.

Building Images Through NEMU and nexus-am

For a custom software image, the README requires absolute paths for three related projects. `NEMU_HOME` points to the NEMU project, `NUTSHELL_HOME` points to the NutShell checkout, and `AM_HOME` points to the cloned AM project. The README specifically names `OSCPU/nexus-am` for the AM repository. These variables let the surrounding build tooling locate each source tree without relying on an implicit current directory.

The README gives this example from the `microbench` application in the AM project:

cd nexus-am/apps/microbench
make ARCH=riscv64-nutshell mainargs=test run

The `ARCH=riscv64-nutshell` selection identifies the NutShell target. `mainargs=test` passes the documented test argument to the microbenchmark. This route is more involved than `make emu` because it requires NEMU, the NutShell source tree, and the AM project to be available and correctly located.

The README does not document dependency versions, environment-variable assignment commands, a complete NEMU compilation procedure, or the exact boot contract for every custom binary. Readers should follow the NEMU and `nexus-am` documentation for those missing setup details. The documented command is still specific enough to establish the intended integration boundary between the software build and the NutShell target.

Building a NutShell Vivado Project for FPGA

FPGA deployment adds board-specific tools and files. The README requires Vivado 2019.1 and the Vivado and SDK settings. Its example creates a project for the `pynq` board:

cd fpga
make PRJ=myproject BOARD=pynq STANDALONE=true

This creates the project under `board/pynq/build/myproject-pynq`. The user then opens the generated project in Vivado and produces the bitstream. The README says that `STANDALONE=true` applies only to the `pynq` board. Other board-specific files are under `fpga/board`, so changing `BOARD` is not equivalent to making every board use the same flow.

The repository also describes SD-card boot. The bitstream must be placed into `BOOT.BIN`, and the card is inserted into the board before powering it on. For the PS-side Linux path, the user opens a serial terminal. For the NutShell RISC-V subsystem, the process is different: the README requires compiling `ddr-loader.c`, sending the loader to the PS, preparing a RISC-V binary whose starting address is `0x80000000`, and using the loader to start the subsystem. The documented build command is:

gcc -O2 -o ddr-loader ddr-loader.c

The loader invocation then takes the board and binary file. The README gives the UART connection as `/dev/ttyUL1` and instructs the user to run `poweroff` on the PS before shutting down the board. This is a concrete lab procedure with several hardware and filesystem dependencies.

NutShell's Toolchain Limits and Upgrade Cost

The main limitation is that NutShell has a narrow, education-oriented operating path. The README documents commands for Mill, simulation, image construction with NEMU and `nexus-am`, Vivado project generation, and the PS-side loader. It does not provide a general package installation procedure, a compatibility matrix for Linux kernels and Debian root filesystems, formal verification results, performance measurements, a documented rollback procedure, or a universal FPGA deployment path. The Debian demonstration is useful evidence that the project has a system-level objective, but it is not a specification of every supported software configuration.

The license creates a separate adoption decision. GitHub classifies the repository license as `Other`, and the README points to the `LICENSE` file. The terms of that file are not reproduced in the README, so the permissions for generated Verilog, modifications, hardware distributions, or commercial use must be checked directly before incorporation into another project. This is a licensing question, not a technical guarantee.

The repository is not archived, and its last push was on 2026-09-22. The only listed release is `release-211228`, dated 2021-12-28. That means recent repository activity exists, but the release history does not show a recent stable release series. Upgrade work may therefore involve dependency compatibility and board-file changes rather than simply selecting a newer tagged artifact.

Choosing NutShell Instead of a Standalone RISC-V Simulator

A standalone RISC-V simulator and NutShell solve different problems. A simulator centers on executing software and observing instruction behavior. NutShell exposes a system-level design that includes Chisel sources, generated Verilog, simulation integration, FPGA support files, and a documented route for loading a program into the RISC-V subsystem. The latter is the relevant choice when the experiment must include processor generation and hardware integration.

NutShell is less convenient when the only requirement is a software execution environment. Its documented simulation path already depends on the repository's generated hardware and prepared image conventions, while its FPGA path adds Vivado, board selection, SD-card preparation, and a PS-side loader. The README does not present NutShell as a replacement for a general-purpose ISA simulator or as a production CPU platform.

For a student, the educational value is the central criterion. For an FPGA experiment, the target board and Vivado version come first. For a production design, the custom LICENSE, old listed release, unspecified software compatibility, and limited operational documentation require further review before adoption.

Editorial conclusion

NutShell fits students and engineers who need an inspectable RISC-V SoC for simulation or FPGA experimentation and can support its documented toolchain. It is a poor fit for production adoption or teams seeking a conventional package with stable releases and broad board support. First review the custom LICENSE, then confirm that the selected FPGA board, Vivado version, software image, and source revision work together.

Frequently asked questions

Official sources

1. Issues
2. OSCPU/NutShell on GitHub
3. Project website
4. README
5. Releases