treewide: small flow fixes, wording

Author: phsauter

README.md

@@ -9,16 +9,16 @@ Croc is developed as part of the PULP project, a joint effort between ETH Zurich
 Croc was successfully taped out in Nov 2024. The chip is called [MLEM](http://asic.ee.ethz.ch/2024/MLEM.html), named after the sound Yoshi makes when eating a tasty fruit.
 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](https://github.com/pulp-platform/croc/tree/mlem-tapeout) branch.
 
-
 ## Architecture
 
 ![Croc block diagram](doc/croc_arch.svg)
 
 The SoC is composed of two main parts:
-- The `croc_domain` containing a CVE2 core (a fork of Ibex), SRAM, an OBI crossbar and a few simple peripherals 
+
+- The `croc_domain` containing a CVE2 core (a 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](https://github.com/openhwgroup/obi/blob/072d9173c1f2d79471d6f2a10eae59ee387d4c6f/OBI-v1.6.0.pdf). 
+The main interconnect is OBI, you can find [the spec online](https://github.com/openhwgroup/obi/blob/072d9173c1f2d79471d6f2a10eae59ee387d4c6f/OBI-v1.6.0.pdf).
 
 The various IPs of the SoC (UART, OBI, debug-module, timer...) come from other PULP repositories and are managed by [Bender](https://github.com/pulp-platform/bender).
 To make it easier to browse and understand, only the currently used files 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`.
@@ -63,87 +63,101 @@ The address map of the default configuration is as follows:
 | `32'h2000_0000` | `32'h2000_1000` | reserved for string formatted user ROM*    |
 
 
-*If people modify Croc we suggest they add a ROM at this address containing additional information 
+*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](https://github.com/pulp-platform/croc/blob/mlem-tapeout/rtl/user_domain/user_rom.sv) may serve as a reference implementation.
 
 ## Flow
+
 ```mermaid
 graph LR;
-	Bender-->Yosys;
-	Yosys-->OpenRoad;
-	OpenRoad-->KLayout;
+  Bender-->Yosys;
+  Yosys-->OpenRoad;
+  OpenRoad-->KLayout;
 ```
+
 1. Bender provides a list of SystemVerilog files
 2. Yosys parses, elaborates, optimizes and maps the design to the technology cells
 3. The netlist, constraints and floorplan are loaded into OpenRoad for Place&Route
 4. The design as def is read by klayout and the geometry of the cells and macros are merged
 
 Currently, the final GDS is still missing the following things:
+
 - metal density fill
 - sealring
+
 These can be added in KLayout, check the [IHP repository](https://github.com/IHP-GmbH/IHP-Open-PDK/tree/main) (possible the dev branch) for a reference script.
 
 ### Example Results
-Cell/Module placement                      |  Routing
-:-----------------------------------------:|:------------------------------------:
-![Chip module view](doc/croc_modules.jpg)  |  ![Chip routed](doc/croc_routed.jpg)
 
+|Cell/Module placement                      |  Routing                             |
+|:-----------------------------------------:|:------------------------------------:|
+|![Chip module view](doc/croc_modules.jpg)  |  ![Chip routed](doc/croc_routed.jpg) |
 
 ## 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](https://github.com/iic-jku/IIC-OSIC-TOOLS).  
 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:
+
 ```sh
 # 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.
 
 An environment setup for bash is provided to get easy access to the tools:
+
 ```sh
 source ethz.env
 ```
 
 Additionally you may prefer to just enter a shell in the pre-installed osic-tools container using:
+
 ```sh
 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) 
+#### 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](https://docs.docker.com/desktop/).  
 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](https://desktop.github.com/download/) 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](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user).
 
 Finally, you can navigate to this directory, open a terminal (PowerShell in Windows) and type:
+
 ```sh
 # Linux only (starts and enters docker container in shell)
-./start_linux.sh
+scripts/start_linux.sh
 # Linux/Mac (starts VNC server on localhost:5901)
-./start_vnc.sh
+scripts/start_vnc.sh
 # Windows (starts VNC server on localhost:5901)
-./start_vnc.bat
+scripts/start_vnc.bat
 ```
 
-If you use the VNC option, open a browser and type `localhost` in the address bar. 
+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](https://github.com/iic-jku/IIC-OSIC-TOOLS/tree/main)
 
 #### Native install (hard)
+
 You need to build/install the required tools manually:
 
 - [Bender](https://github.com/pulp-platform/bender#installation): Dependency manager
@@ -153,60 +167,67 @@ You need to build/install the required tools manually:
 - (Optional) [Verilator](https://github.com/verilator/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:
+
 ```sh
-make checkout
-make yosys
-make openroad
-make klayout
+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:
-```sh
-make verilator
-```
 
-If you have Questasim/Modelsim, you can also run:
 ```sh
-make vsim
+cd sw && make all
+cd ../verilator && ./run_verilator.sh --build --run ../sw/bin/helloworld.hex
 ```
 
+If you have Questasim/Modelsim, you can also run:
 
-The most important make targets are documented, you can list them with:
 ```sh
-make help
+cd vsim && ./run_vsim.sh --build --run ../sw/bin/helloworld.hex
 ```
 
+All `run_` scripts have a `--help` you can use to orient yourself.
+
 ### Building on Croc
+
 To add your own design, we recommend creating a new directory under `rtl/` or put single source files (small designs) into `rtl/user_domain`, then go into `Bender.yml` and add the files in the indicated places.
 This will make Bender aware of the files and any script it contains will contain your design as well.
 
 Then re-generate the default synthesis file-list:
+
 ```sh
-make yosys-flist
+cd yosys && ./run_synthesis.sh --flist
+cd ../verilator && ./run_verilator.sh --flist
 ```
 
 If you want to add an existing design and it already containts a `Bender.yml` in its repository, you can add it as a dependency in the `Bender.yml` and reading the guide below.
 
 ## Bender
+
 The dependency manager [Bender](https://github.com/pulp-platform/bender) is used in most pulp-platform IPs.
 Usually each dependency would be in a seperate repository, each with a `Bender.yml` file to describe where the RTL files are, how you can use this dependency and which additional dependency it has.
 In the top level repository (like this SoC) you also have a `Bender.yml` file but you will commonly find a `Bender.lock` file. It contains the resolved tree of dependencies with specific commits for each. Whenever you run a command using Bender, this is the file it uses to figure out where things are.
 
 Below is a small guide aimed at the usecase for this project. The Bender repo has a more extensive [Command Guide](https://github.com/pulp-platform/bender?tab=readme-ov-file#commands).
 
 ### Checkout
-Using the command `bender checkout` Bender will check the lock file and download the specified commits from the repositories (usually into a hidden `.bender` directory). 
+
+Using the command `bender checkout` Bender will check the lock file and download the specified commits from the repositories (usually into a hidden `.bender` directory).
 
 ### Update
+
 Running `bender update` on the other hand will resolve the entire tree again and re-generate the lock file (you usually have to resolve some version/revision conflicts if multiple things use the same dependency).
 
 **Remember:** always test everything again if you generate a new `Bender.lock`, it is the same as modifying RTL.
 
 ### Local Versions
+
 For this repository, we use a subcommand called `bendor vendor` together with the `vendor_package` section in `Bender.yml`.
 `bendor vendor` can be used to Benderize arbitrary repositories with RTL in it. The dependencies are already 'checked out' into `rtl/<IP>`. Each file or directory from the repository is mapped to a local path in this repo.
 Fixes and changes to each IPs `rtl/<IP>/Bender.yml` are managed by `bender vendor` in `rtl/patches`.
@@ -217,7 +238,9 @@ To save a fix/change as a patch, stage it in git and then run `bender vendor pat
 **Note:** using `bender vendor` in this repository to change the local versions of the IPs requires an up-to-date version of Bender, specifically it needs to include [PR 179](https://github.com/pulp-platform/bender/pull/179).
 
 ### Targets
+
 Another thing we use are targets (in the `Bender.yml`), together they build different views/contexts of your RTL. For example without defining any targets the technology independent cells/memories are used (in `rtl/tech_cells_generic/`) but if we use the target `ihp13` then the same modules contain a technology-specific implementation (in `ihp13/`). Similar contexts are built for different simulators and other things.
 
 ## License
+
 Unless specified otherwise in the respective file headers, all code checked into this repository is made available under a permissive license. All hardware sources and tool scripts are licensed under the Solderpad Hardware License 0.51 (see `LICENSE.md`). All software sources are licensed under Apache 2.0.

artistic/run_artistic.sh

@@ -2,13 +2,16 @@
 # Copyright (c) 2026 ETH Zurich and University of Bologna.
 # Licensed under the Apache License, Version 2.0, see LICENSE for details.
 # SPDX-License-Identifier: Apache-2.0
+#
+# Authors:
+# - Thomas Benz <tbenz@iis.ee.ethz.ch>
 
 set -e  # Exit on error
 set -u  # Error on undefined vars
 
 
 ################
-### Setup
+# Setup
 ################
 # Source environment
 source "../env.sh"
@@ -17,7 +20,7 @@ export GITHUB_REPOSITORY="${GITHUB_REPOSITORY:-localhost}" # Get commit in CI ru
 
 
 ################
-### Helpers
+# Helpers
 ################
 
 show_help() {
@@ -29,14 +32,14 @@ Usage:
 
 Options:
     --help, -h          Show this help message
-    --dry-run, -n       Don't actually run any command; just print them
-    --verbose, -v       Print commands before executing them
+    --dry-run, -n       Only print commands instead of executing
+    --verbose, -v       Print commands while executing
     --logo SRC_FILE     Create an ASIC art on the top metal layer from 'artistic/src/logo_chip.svg'
                         The source file is seen relative to the 'klayout/out' directory.
     --render            Render the logo-enhanced GDS
     --outline           Annotate the render with module oulines defined in 'artistic/src/croc_modules.json'
     --render-map        Render and generate an OpenStreetMap DB
-    --cleanup           Cleanup intermittend files
+    --cleanup           Cleanup intermittent files
 
 EOF
     exit 0
@@ -167,7 +170,7 @@ cleanup() {
 
 
 ####################
-### Parse Arguments
+# Parse Arguments
 ####################
 
 DRYRUN=0

env.sh

@@ -1,8 +1,12 @@
 #!/bin/bash
-# Copyright (c) 2024 ETH Zurich and University of Bologna.
+# Copyright (c) 2026 ETH Zurich and University of Bologna.
 # Licensed under the Apache License, Version 2.0, see LICENSE for details.
 # SPDX-License-Identifier: Apache-2.0
 #
+# Authors:
+# - Philippe Sauter <phsauter@iis.ee.ethz.ch>
+# - Thomas Benz     <tbenz@iis.ee.ethz.ch>
+#
 # Environment setup for Croc SoC ASIC flow
 # This file is sourced by all scripts to set up tool paths and PDK location
 
@@ -15,9 +19,10 @@ fi
 echo "[INFO][ENV] Croc root: $CROC_ROOT"
 
 
-################
-## PDK Discovery (priority: PDK_ROOT → technology/ → ihp13/pdk/)
-################
+###################
+# PDK Discovery
+###################
+# priority: technology/ over ihp13/pdk/
 
 if [[ -d "${CROC_ROOT}/technology" ]]; then
 
@@ -67,42 +72,18 @@ fi
 echo "[INFO][ENV] PDK root: $PDK_ROOT"
 echo "[INFO][ENV] KLayout path: $KLAYOUT_PATH"
 
-export PDK=ihp-sg13g2
-
 
-################
-## Project Settings ##
-################
+######################
+# Project Settings
+######################
 export PROJ_NAME="${PROJ_NAME:-croc}"
 export TOP_DESIGN="${TOP_DESIGN:-croc_chip}"
 export DUT_DESIGN="${DUT_DESIGN:-croc_soc}"
 
-################
-## Directory Structure ##
-################
-# Yosys
-export YOSYS_DIR="${CROC_ROOT}/yosys"
-export YOSYS_OUT="${YOSYS_DIR}/out"
-export YOSYS_REPORTS="${YOSYS_DIR}/reports"
-export YOSYS_TMP="${YOSYS_DIR}/tmp"
-
-# OpenROAD
-export OR_DIR="${CROC_ROOT}/openroad"
-export OR_OUT="${OR_DIR}/out"
-export OR_REPORTS="${OR_DIR}/reports"
-export OR_SAVE="${OR_DIR}/save"
-
-# KLayout
-export KLAYOUT_DIR="${CROC_ROOT}/klayout"
-
-# Software
-export SW_DIR="${CROC_ROOT}/sw"
-export SW_BIN="${SW_DIR}/bin"
-
-################
-## Netlist Paths ##
-################
-export NETLIST="${YOSYS_OUT}/${TOP_DESIGN}_yosys.v"
-export NETLIST_DEBUG="${YOSYS_OUT}/${TOP_DESIGN}_yosys_debug.v"
 
+###################
+# Netlist Paths
+###################
+export NETLIST="${CROC_ROOT}/yosys/${TOP_DESIGN}_yosys.v"
+export NETLIST_DEBUG="${CROC_ROOT}/yosys/${TOP_DESIGN}_yosys_debug.v"