Croc System-on-Chip

A simple SoC for education using PULP IPs. Croc includes all scripts necessary to produce a nearly finished chip in IHPs open-source 130nm technology.

As it is oriented towards education, it forgoes some configurability to increase readability of the RTL and scripts.

Croc is developed as part of the PULP project, a joint effort between ETH Zurich and the University of Bologna.

Croc was successfully taped out in Nov 2024 in the chip MLEM, named after the sound Yoshi makes when eating a tasty fruit. MLEM's core functionality was verified on real silicon early 2026.
MLEM was designed and prepared for tapeout by ETHZ students as a bachelor project. The exact code and scripts used for the tapeout can be seen in the frozen mlem-tapeout branch.

Architecture

Croc block diagram

The SoC is composed of two main parts:

The croc_domain containing a CVE2 core (a more minimal fork of Ibex), SRAM, an OBI crossbar and a few simple peripherals
The user_domain where students are invited to add their own designs or other open-source designs (peripherals, accelerators...)

The main interconnect is OBI, you can find the spec online.

The various IPs of the SoC (UART, OBI, debug-module, timer...) come from other PULP repositories and are managed by Bender. To make it easier to browse and understand, only used or important building blocks are included in rtl/<IP>. You may want to explore the repositories of the respective IPs to find their documentation or additional functionality, the urls are in Bender.yml.

Configuration

The main SoC configurations are in rtl/croc_pkg.sv:

| Parameter | Default | Function | |---------------------|------------------|-------------------------------------------------------| | PulpJtagIdCode | 32'h1C0C_5DB3 | Debug module ID code | | iDMAEnable | 0 | Enable optional DMA (see rtl/idma) | | NumSramBanks | 2 | Number of memory banks | | SramBankNumWords | 512 | Number of 32bit words in a memory bank | | BootAddr | 32'h1000_0000 | Default boot address set in 'soc_ctrl' register | | CrocAddrMap | see 'Memory Map' | Routing rules used for the main crossbar | | PeriphAddrMap | see 'Memory Map' | Routing rules used for the peripheral demuliplexer |

Further configurations can be made in rtl/core_wrap.sv (core specifics) and rtl/croc_soc.sv (connectivity between domains and to/from outside).

The SRAMs are instantiated via a technology wrapper called tc_sram_impl (tc: tech_cells), the technology-independent implementation is in rtl/tech_cells_generic/tc_sram_impl.sv. A number of SRAM configurations are implemented using IHP130 SRAM memories in ihp13/tc_sram_impl.sv. If an unimplemented SRAM configuration is instantiated it will result in a tc_sram_blackbox module which can then be easily identified from the synthesis results.

Bootmodes

Currently the only way to boot is via JTAG.

Memory Map

If possible, the memory map should remain compatible with Cheshire's memory map.
Further each new subordinate should occupy multiples of 4KB of the address space (32'h0000_1000).

The address map of the default configuration is as follows:

| Start Address | Stop Address | Description | |-----------------|-----------------|--------------------------------------------| | 32'h0000_0000 | 32'h0004_0000 | Debug module (JTAG) | | 32'h0200_0000 | 32'h0200_4000 | Bootrom | | 32'h0204_0000 | 32'h0208_0000 | CLINT peripheral | | 32'h0300_0000 | 32'h0300_1000 | SoC control/info registers | | 32'h0300_2000 | 32'h0300_3000 | UART peripheral | | 32'h0300_5000 | 32'h0300_6000 | GPIO peripheral | | 32'h0300_A000 | 32'h0300_B000 | Timer peripheral | | 32'h0300_B000 | 32'h0300_C000 | (optional) DMA configuration | | 32'h1000_0000 | +SRAM_SIZE | Memory banks (SRAM) | | 32'h2000_0000 | 32'h8000_0000 | Passthrough to user domain | | 32'h2000_0000 | 32'h2000_1000 | reserved for user ROM text* |

*If people modify Croc we suggest they add a ROM at this address containing additional information like the names of the developers, a project link or similar. This can then be written out via UART.
We ask people to format the ROM like a C string with zero termination and using ASCII encoding if feasible.
The MLEM user ROM may serve as one possible reference implementation.

Flow

graph LR;
  Bender-->Yosys;
  Yosys-->OpenRoad;
  OpenRoad-->KLayout;

Bender provides a list of SystemVerilog files
Yosys parses, elaborates, optimizes and maps the design to the technology cells
The netlist, constraints and floorplan are loaded into OpenRoad for Place&Route
The design as def is read by klayout and the geometry of the cells and macros are merged

Example Results

Requirements

We are using the excellent docker container maintained by Harald Pretl. If you get stuck with installing the tools, we urge you to check the Tool Repository.
The current supported version is 2025.12, no other version is officially supported.

ETHZ systems

ETHZ Design Center maintains an internal version of the IHP PDK, with integrations into all tools we have access to. For this reason if you work on the ETH systems it is recommended to use the icdesign tool (cockpit) instead of the liked Github repo.
You can directly create a cockpit directory inside the croc directory:

# Make sure you are in <somedir>/croc
# the checked-out repository
icdesign ihp13 -nogui

The setup is guided by the .cockpitrc configuration file. If you need different macros or another version of the standard cells you can change it accordingly.

Yyou may prefer to just enter a shell in the pre-installed osic-tools container using:

oseda bash
# specific version eg: oseda -2025.12 bash

Other systems

Note: this has currently only been tested on Ubuntu and RHEL Linux.

Docker (easy)

There are two possible ways, the easiest way is to install docker and work in the docker container, you can follow the install guides on the Docker Website.
You do not need to manually download the container image, this will be done when running the script. If you do not have git installed on your system, you also need to install Github Desktop and then clone this git repository.

It is a good idea to grant non-root (sudo) users access to docker, this is decribed in the Docker Article.

Finally, you can navigate to this directory, open a terminal (PowerShell in Windows) and type:

# Linux only (starts and enters docker container in shell)
scripts/start_linux.sh
# Linux/Mac (starts VNC server on localhost:5901)
scripts/start_vnc.sh
# Windows (starts VNC server on localhost:5901)
scripts/start_vnc.bat

If you use the VNC option, open a browser and type localhost in the address bar. This should connect you to the VNC server, the password is abc123, then test by right-clicking somewhere, starting the terminal and typing ls.
You should see the files in this repository again.

Now you should be in an Ubuntu environment with all tools pre-installed for you.
If something does not work, refer to the upstream IIC-OSIC-Tools.

To stop the VNC server, run the start script again and then select between stopping or stop and remove the running docker container.

Native install (hard)

You need to build/install the required tools manually:

Bender: Dependency manager
Yosys: Synthesis tool
Yosys-Slang: SystemVerilog frontend for Yosys
OpenRoad: Place & Route tool
(Optional) Verilator: Simulator
(Optional) Questasim/Modelsim: Simulator

Getting started

The SoC is fully functional as-is and a simple software example is provided for simulation. To run the synthesis and place & route flow execute:

git submodule update --init --recursive
cd yosys && ./run_synthesis.sh --synth
cd ../openroad && ./run_backend.sh --all
cd ../klayout && ./run_finishing.sh --gds

To simulate you can use:

cd sw && make all
cd ../verilator && ./run_verilator.sh --build --run ../sw/bin/helloworld.hex

If you have Questasim/Modelsim, you can also run:

cd vsim && ./run_vsim.sh --build --run ../sw

Croc

Install / Use

README