From c886887b991e28b1dd892856aa9afa7c05eeddb5 Mon Sep 17 00:00:00 2001 From: Andrei Solodovnikov Date: Wed, 18 Jun 2025 15:37:25 +0300 Subject: [PATCH 1/5] Add user guide about building cheshire on Windows --- docs/um/index.md | 1 + docs/um/windows.md | 94 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 95 insertions(+) create mode 100644 docs/um/windows.md diff --git a/docs/um/index.md b/docs/um/index.md index da1dc7f50..6c264bb84 100644 --- a/docs/um/index.md +++ b/docs/um/index.md @@ -4,3 +4,4 @@ The *user manual* provides detailed reference information on Cheshire: - [Architecture](arch.md): Describes the hardware design, features, and configuration of Cheshire. - [Software Stack](sw.md): Describes how to run code on Cheshire and its Linux boot flow. +- [Windows](windows.md): Describes how to build targets and run simulation on Windows platform using WSL2. diff --git a/docs/um/windows.md b/docs/um/windows.md new file mode 100644 index 000000000..236e26fc8 --- /dev/null +++ b/docs/um/windows.md @@ -0,0 +1,94 @@ +# Using the Cheshire Repository on Windows via WSL2 + +This guide describes how to work with the [Cheshire](https://github.com/pulp-platform/cheshire) repository in a Windows environment. + +While it is technically possible to install all required dependencies (Bender, CMake, Python and its packages, GCC, and a RISC-V cross-compiler) natively on Windows, dependency build scripts are likely to fail. The main reasons include: + +- **Path incompatibility**: Windows uses backslashes (`\`) in paths, which are interpreted as escape characters in many scripts. +- **Missing Unix utilities**: The build scripts rely on utilities not present in the Windows environment. + +To resolve these issues, the scripts are executed within the **Windows Subsystem for Linux (WSL2)** environment. Using WSL2 avoids problems caused by the wide variety of Windows terminals (cmd, PowerShell, MSYS, Cygwin, Git Bash, etc.), each with its own path interpretation and limitations. Furthermore, WSL2 allows running host-side programs such as **Vivado** or **QuestaSim**, which is leveraged in this setup. + +Confirmed working scenarios include: + +- Firmware synthesis (e.g., for target `chs-xilinx-vcu128`) +- Simulation using QuestaSim + +--- + +## 1. Prerequisites + +### Install WSL2 + +Follow Microsoft's official guide to set up WSL2: [How to install Linux on Windows with WSL](https://learn.microsoft.com/en-us/windows/wsl/install). + +### Install Dependencies +Once WSL2 is installed, open a WSL terminal and follow the [Cheshire Getting Started guide](https://pulp-platform.github.io/cheshire/gs/#dependencies) to install dependencies. + +### Install Required EDA Tools on Windows + +- For **synthesis**: Install **Vivado** on the Windows host. +- For **simulation**: Install **QuestaSim** (note that **VCS** is not available for Windows). + +## 2. Adjust WSL Mount Points + +By default, WSL mounts Windows drives under `/mnt/`. This creates inconsistencies between Windows and WSL paths. To align the mount point structure, change the root mount location to `/` by editing `/etc/wsl.conf` inside WSL: + +```conf +[automount] +enabled = true +mountFsTab = false +root = / +options = "metadata,umask=22,fmask=11" +``` + +Then restart WSL from Windows: + +```powershell +wsl --shutdown +``` + +Launch WSL again afterward. + +## 3. Working with Paths + +After the mount configuration change: + +- in WSL, a Windows path looks like: `/c/Users/your_name/Desktop`; +- in Windows, the same path is: `C:\Users\your_name\Desktop`. + +To convert between formats, one can use the wslpath utility: + +```bash +wslpath -u 'C:\Users\your_name\Desktop' # to Unix format, results in: + # /c/Users/your_name/Desktop +wslpath -w /c/Users/your_name/Desktop # to Windows format, results in: + # C:\Users\your_name\Desktop +wslpath -m /c/Users/your_name/Desktop # to Windows format with '/' as + # delimiter, results in: + # C:/Users/your_name/Desktop +``` + +## 4. Synthesis and Simulation + +Follow the rest of the [tool configuration guide](https://pulp-platform.github.io/cheshire/gs/#tool-paths) as usual. However, if you are performing synthesis with Vivado installed on Windows, you [need to define](https://pulp-platform.github.io/cheshire/tg/xilinx/) the `VIVADO` environment variable using cmd.exe: + +```bash +# Example: +export VIVADO="cmd.exe /c/Xilinx/Vivado/2023.1/bin/vivado.bat" +``` + +### Tested Targets + +- `make all` +- `make chs-xilinx-vcu128` — Synthesis via Vivado on Windows (called from WSL) + +### QuestaSim Simulation + +QuestaSim (Windows version) works when launched via WSL using the `.exe` suffix: + +```bash +vsim.exe +``` + +You can run Windows GUI and console applications from within WSL without issues (via `-gui` and `-batch` flags respectively). From 1db0a369b9dfd3ccd92d93782173a2e33ce951e1 Mon Sep 17 00:00:00 2001 From: Andrei Solodovnikov Date: Thu, 19 Jun 2025 15:02:50 +0300 Subject: [PATCH 2/5] Add "Potential Issues" section to Windows UM --- docs/um/windows.md | 40 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 38 insertions(+), 2 deletions(-) diff --git a/docs/um/windows.md b/docs/um/windows.md index 236e26fc8..72fedd456 100644 --- a/docs/um/windows.md +++ b/docs/um/windows.md @@ -23,6 +23,7 @@ Confirmed working scenarios include: Follow Microsoft's official guide to set up WSL2: [How to install Linux on Windows with WSL](https://learn.microsoft.com/en-us/windows/wsl/install). ### Install Dependencies + Once WSL2 is installed, open a WSL terminal and follow the [Cheshire Getting Started guide](https://pulp-platform.github.io/cheshire/gs/#dependencies) to install dependencies. ### Install Required EDA Tools on Windows @@ -30,7 +31,7 @@ Once WSL2 is installed, open a WSL terminal and follow the [Cheshire Getting Sta - For **synthesis**: Install **Vivado** on the Windows host. - For **simulation**: Install **QuestaSim** (note that **VCS** is not available for Windows). -## 2. Adjust WSL Mount Points +## 2. Configure WSL By default, WSL mounts Windows drives under `/mnt/`. This creates inconsistencies between Windows and WSL paths. To align the mount point structure, change the root mount location to `/` by editing `/etc/wsl.conf` inside WSL: @@ -50,6 +51,8 @@ wsl --shutdown Launch WSL again afterward. +Check [Potential Issues](#potential-issues) section for additional configuration steps if needed. + ## 3. Working with Paths After the mount configuration change: @@ -75,7 +78,7 @@ Follow the rest of the [tool configuration guide](https://pulp-platform.github.i ```bash # Example: -export VIVADO="cmd.exe /c/Xilinx/Vivado/2023.1/bin/vivado.bat" +export VIVADO="/c/Windows/System32/cmd.exe /c/Xilinx/Vivado/2023.1/bin/vivado.bat" ``` ### Tested Targets @@ -92,3 +95,36 @@ vsim.exe ``` You can run Windows GUI and console applications from within WSL without issues (via `-gui` and `-batch` flags respectively). + +## Potential Issues + +### PATH variable + +By default, WSL imports the Windows host's `PATH` variable, which often includes paths containing spaces (e.g., paths to `Program Files`). This can cause issues during the build process. For example, when building the `images` target in the `cva6-sdk` submodule, you might encounter the following error: + +```text +PATH contains spaces and or tabs, or newline characters. That won't work. Fix the PATH. +``` + +While it is [technically possible](https://gist.github.com/deadash/82413acc7b59c0dc127c192ddfc608bb) to escape spaces in `PATH`, this approach will **not** work for this particular build target, which requires **removing** all problematic entries from `PATH`. + +The general workaround to this problem is to filter `PATH` at shell startup. Add the following line to the end of your ~/.bashrc (or relevant shell init file): + +```bash +export PATH=$(echo "$PATH" | tr ':' '\n' | grep -v ' ' | paste -sd:) +``` + +This will remove all paths with spaces from your `PATH` variable. + +Restart the shell or source the edited file to apply the changes. This solution retains useful Windows paths such as `/c/Windows/System32/`, allowing tools like `cmd.exe` to remain accessible. If your simulator is installed in a directory without spaces, you can continue to run it via `vsim.exe` from within WSL. + +Alternatively, you can disable Windows path import in WSL by adding the following lines to `/etc/wsl.conf`: + +```conf +[interop] +appendWindowsPath = false +``` + +Shutdown and launch WSL again afterward. A disadvantage of this approach is that you will no longer be able to run Windows host executables (e.g., `cmd.exe`, `vsim.exe`) without specifying the full path. + +> **Note:** Building Cheshire targets will generally work regardless of whether you apply any of the suggested `PATH` adjustments. However, modifying `PATH` may be necessary for building certain submodule targets, such as the `images` target in the `cva6-sdk` submodule. From 012efa78f345b1567aaac395c547a7ad9c40cd9d Mon Sep 17 00:00:00 2001 From: Andrei Solodovnikov Date: Thu, 19 Jun 2025 15:59:13 +0300 Subject: [PATCH 3/5] Fix error message example in Windows UG --- docs/um/windows.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/um/windows.md b/docs/um/windows.md index 72fedd456..074ab68c7 100644 --- a/docs/um/windows.md +++ b/docs/um/windows.md @@ -103,7 +103,8 @@ You can run Windows GUI and console applications from within WSL without issues By default, WSL imports the Windows host's `PATH` variable, which often includes paths containing spaces (e.g., paths to `Program Files`). This can cause issues during the build process. For example, when building the `images` target in the `cva6-sdk` submodule, you might encounter the following error: ```text -PATH contains spaces and or tabs, or newline characters. That won't work. Fix the PATH. +Your PATH contains spaces, TABs, and/or newline (\n) characters. +This doesn't work. Fix you PATH. ``` While it is [technically possible](https://gist.github.com/deadash/82413acc7b59c0dc127c192ddfc608bb) to escape spaces in `PATH`, this approach will **not** work for this particular build target, which requires **removing** all problematic entries from `PATH`. From ca5ed7f621e053de4ece14ea5bc7c8c9f402cd1d Mon Sep 17 00:00:00 2001 From: Andrei Solodovnikov Date: Fri, 20 Jun 2025 17:02:50 +0300 Subject: [PATCH 4/5] Add "File system problems" section to Windows UM --- docs/um/windows.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/um/windows.md b/docs/um/windows.md index 074ab68c7..9da939faf 100644 --- a/docs/um/windows.md +++ b/docs/um/windows.md @@ -98,6 +98,8 @@ You can run Windows GUI and console applications from within WSL without issues ## Potential Issues +All currently known issues are related to building Buildroot, which is included as part of the `cva6-sdk` submodule. These problems may occur, for example, when attempting to build a Linux image for a synthesizable system. + ### PATH variable By default, WSL imports the Windows host's `PATH` variable, which often includes paths containing spaces (e.g., paths to `Program Files`). This can cause issues during the build process. For example, when building the `images` target in the `cva6-sdk` submodule, you might encounter the following error: @@ -129,3 +131,25 @@ appendWindowsPath = false Shutdown and launch WSL again afterward. A disadvantage of this approach is that you will no longer be able to run Windows host executables (e.g., `cmd.exe`, `vsim.exe`) without specifying the full path. > **Note:** Building Cheshire targets will generally work regardless of whether you apply any of the suggested `PATH` adjustments. However, modifying `PATH` may be necessary for building certain submodule targets, such as the `images` target in the `cva6-sdk` submodule. + +### File system problems + +Even with the `PATH` variable adjusted to be compatible with Buildroot, you may encounter another issue when running `make images`. The error will look like: + +```text +riscv64-buildroot-linux-gnu/bin/ld: cannot find Scrt1.o: No such file or directory +riscv64-buildroot-linux-gnu/bin/ld: cannot find -lc +collect2: error: ld returned 1 exit status +``` + +This issue typically occurs when attempting to build Buildroot (as part of the `cva6-sdk` submodule) from within WSL **while the project directory resides on a Windows-mounted drive**. This is likely due to limitations in how symbolic links or other file system features are handled on mounted Windows file systems in WSL. + +To work around this, you can instruct Buildroot to perform the compilation in a separate output directory located **within the native WSL file system** (e.g., your home directory or `/tmp`). + +A patch enabling this behavior is available [here](https://gist.github.com/HepoH3/c0005d711c1291e7a935d4d4488f4e59). + +After applying the patch, you can run the build from a Windows-mounted project directory using a command like: + +```bash +make images BUILDROOT_OUT=~/buildroot_out +``` From e9f9be2f8eb48b990bce0c92e5b712db629c174b Mon Sep 17 00:00:00 2001 From: Andrei Solodovnikov Date: Sat, 28 Feb 2026 20:52:10 +0300 Subject: [PATCH 5/5] docs: Fix export VIVADO variable example in Windows UG --- docs/um/windows.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/um/windows.md b/docs/um/windows.md index 9da939faf..1c4156ed1 100644 --- a/docs/um/windows.md +++ b/docs/um/windows.md @@ -78,7 +78,7 @@ Follow the rest of the [tool configuration guide](https://pulp-platform.github.i ```bash # Example: -export VIVADO="/c/Windows/System32/cmd.exe /c/Xilinx/Vivado/2023.1/bin/vivado.bat" +export VIVADO="/c/Windows/System32/cmd.exe /C 'C:/Xilinx/Vivado/2023.1/bin/vivado.bat'" ``` ### Tested Targets