diff --git a/CHANGELOG.md b/CHANGELOG.md index 542eb153d..24cabe393 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -132,6 +132,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0. - Switch to a better buildroot mirror - CI frees up space in the runner before building a toolchain - Update documentation + - Enhance Cheshire's documentation for better workflow integration with Ara ## 3.0.0 - 2023-09-08 diff --git a/cheshire/README.md b/cheshire/README.md index 653310f28..74c771ca4 100644 --- a/cheshire/README.md +++ b/cheshire/README.md @@ -4,12 +4,33 @@ Ara can be synthesized on a VCU128 FPGA and boot Linux through the Cheshire SoC. Our entry point is to generate a custom `add_sources.vcu128.tcl` file with specific Ara targets, copy this file into the Cheshire directory, and then use the default Cheshire compile flow, which will use our provided TCL file +## Requirements +From Cheshire's [web documentation](https://pulp-platform.github.io/cheshire/gs/#dependencies), ensure you have the next dependencies: + +- GNU make >= 3.82 +- CMake >= 3.24.0 +- Python >= 3.11 +- Bender >= 0.27.1 +- RISCV GCC >= 11.2.0 + +> [!TIP] +> Check [Bender](https://github.com/pulp-platform/bender) repository to install it + +For Python dependencies, it is highly recommended to create a virtual environment and install all packages listed in `requirements.txt` + +```bash +python3 -m venv .venv +source .venv/bin/activate + +pip install -r requirements.txt +``` + ## How to Use -Ara should be instantiated as a submodule of Cheshire. This means that the Ara repo should be downloaded through `bender checkout` from the Cheshire directory. Then, Ara's path can be retrived using `bender path ara`. +Ara should be instantiated as a submodule of Cheshire. This means that the Ara repo should be downloaded through `bender checkout` from the Cheshire directory, more specifically, the `mp/ara-pulp-v2` branch, which includes the CVA6 connected to the Ara. Then, Ara's path can be retrived using `bender path ara`. ```bash -git clone git@github.com:pulp-platform/cheshire.git +git clone --branch=mp/ara-pulp-v2 https://github.com/pulp-platform/cheshire.git cd cheshire git checkout ${COMMIT} bender checkout @@ -19,6 +40,10 @@ cd ${ARA_ROOT} ## FPGA and OS flow +> [!WARNING] +> Ensure that your `$PATH` variable includes ONLY those binaries listed above as well as default system's binaries. Your `$PATH` should look something like follows: +> `/path/to/RISCV>=11.2.0:/path/to/bender:/path/to/cmake>= 3.24.0/:/path/to/python>= 3.11:/bin:/usr/bin:etc` + ### LINUX-RVV Kernels Compile kernels to be run on the FPGA under Linux (this will also install the buildroot toolchain) @@ -39,6 +64,8 @@ cd ${ARA_ROOT}/cheshire/sw make linux-img # Generate Cheshire's Linux img +export VIVADO="/path/to/Vivado/20XX.X/bin/vivado" + cd ${ARA_ROOT}/cheshire make ara-chs-image ``` @@ -64,7 +91,7 @@ cd ${ARA_ROOT}/cheshire make ara-chs-xilinx-program ``` -For more information, see Cheshire's documentation (https://pulp-platform.github.io/cheshire/tg/xilinx). +Every output will be in `cheshire/target/xilinx` directory. For more information, see Cheshire's documentation (https://pulp-platform.github.io/cheshire/tg/xilinx). ### Example @@ -199,4 +226,4 @@ This method ensures that we can extend and customize the compile flow for our sp - HOST_TOOLCHAIN_SUFFIX: the host GCC and G++ should be sufficiently up to date to build the buildroot cross compiler. For environments that track the program version with suffixes, this variable helps choose the correct host compiler version. Use this variable only if needed when installing the buildroot toolchain. - BOARD: name of the board, e.g., `vcu128`. - CHS_XILINX_HWS_URL: URL of the FPGA, if connected to the net. - - CHS_XILINX_HWS_PATH: physical PATH of the FPGA. \ No newline at end of file + - CHS_XILINX_HWS_PATH: physical PATH of the FPGA. diff --git a/cheshire/requirements.txt b/cheshire/requirements.txt new file mode 100644 index 000000000..1917b67f1 --- /dev/null +++ b/cheshire/requirements.txt @@ -0,0 +1,28 @@ +# University Institute of Applied Microelectronics (https://www.iuma.ulpgc.es/) +# Author: Jorge López Viera +# Created: 20/05/2026 +# This file includes the Python's dependencies for +# both the Cheshire and Ara + +requests +hjson +mako +pyyaml +tabulate +yapf +mkdocs +mkdocs-material +markdown-grid-tables +tclint==0.4.2 +flatdict>=4.1.0 +setuptools==80 +peakrdl>=1.5.0 +peakrdl-rawheader>=0.2.3 +dataclasses +gitpython +jsonref +jsonschema +yamlfmt +numpy +matplotlib +scikit-learn