BlackParrot Simulation Environment
This repository is the main development meta-repository of the BlackParrot processor BlackParrot. It should track close to the bleeding edge of the BlackParrot RTL and BlackParrot SDK repos. Because this is a low-level simulation environment, there's very little else in this repo.
BlackParrot Repository Overview
- black-parrot/ contains the BlackParrot RTL and basic simulation testbench environment
- black-parrot-sdk/ contains the BlackParrot Software Development Kit. More details can be found in the SDK README.md
- black-parrot-tools/ contains some open-source tools used to run basic BlackParrot simulations
- docker/ contains files needed for a Docker-based simulation environment
Tire Kick
Users who just want to test their setup and run a minimal BlackParrot test should run the following:
# Clone the latest repo
git clone https://github.com/black-parrot/black-parrot-sim.git
cd black-parrot-sim
# Install a minimal set of tools and libraries
# For faster builds, make prep_lite -j is parallelizable!
make prep_lite
# Running your first test
make -C black-parrot/bp_top/syn tire_kick
This should output (roughly)
Hello world!
[CORE0 FSH] PASS
[CORE0 STATS]
clk : 220
instr : 66
mIPC : 300
All cores finished! Terminating...
Getting Started
Prerequisites
CentOS 7+
To install most dependencies, execute the following command:
sudo yum install autoconf automake bash bc binutils bison bzip2 cpio dtc expat-devel file flex gawk gcc gcc-c++ git gmp-devel gzip gtkwave java-11-openjdk-headless libmpc-devel libuuid-devel make mpfr-devel patch patchutils perl perl-ExtUtils-MakeMaker python3 python3-pip rsync sed tar tcl tcl-devel tk tk-devel texinfo unzip vim vim-common virtualenv which zlib-devel help2man readline-devel libreadline-devel libffi-devel wget openssl-devel epel-release centos-release-scl scl-utils
On CentOS 7, some tools provided by the base repository are too old to satisfy the requirements. We suggest using the Software Collections (SCL) to obtain newer versions.
sudo yum install centos-release-scl scl-utils
sudo yum install devtoolset-9 rh-git218
scl enable devtoolset-9 rh-git218 bash
To automatically enable these tools from SCL on new terminals, add the following line to ~/.bashrc:
source scl_source enable devtoolset-9 rh-git218
Moreover, the cmake package on CentOS 7 is CMake 2 while we need CMake 3. We suggest installing CMake 3 from EPEL:
sudo yum install epel-release
sudo yum install cmake3
On CentOS 8 and later, the cmake package is CMake 3 and works well without CMAKE=cmake3:
sudo yum install cmake
Ubuntu
sudo apt-get install apt-utils tzdata git vim gettext-base uuid-dev default-jre bash autoconf automake autotools-dev curl libmpc-dev libmpfr-dev libgmp-dev gawk build-essential bison flex texinfo gperf libtool patchutils bc zlib1g-dev libexpat-dev wget byacc device-tree-compiler python gtkwave python-yaml pkg-config swig python3-dev pip virtualenv help2man tcl8.6-dev libreadline-dev libffi-dev software-properties-common lsb-release
# Some ubuntu distros do not provide a default symlink here
sudo ln -nsf /usr/bin/tclsh8.6 /usr/bin/tclsh
Update Cmake
Some Ubuntu installations have too old a default CMake, we can update it with the following:
wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | gpg --dearmor - | sudo tee /etc/apt/trusted.gpg.d/kitware.gpg >/dev/null
sudo apt-add-repository "deb https://apt.kitware.com/ubuntu/ $(lsb_release -cs) main" && sudo apt update && sudo apt install -y cmake
Other Prerequisites
We need the orderedmultidict Python package too, but it is not packaged by default. Installing it from PyPI works:
pip install --user orderedmultidict
BlackParrot has been tested extensively on CentOS 7. We have many users who have used Ubuntu for development. If not on a relatively recent version of these OSes, we suggest using a Docker image.
Ubuntu on Windows WSL 2.0 seems to work for most things, but you may encounter errors with more complex operations. For instance, compiling Linux is known not to work in this environment. This is considered an experimental build.
Docker build
For a painless Ubuntu build, download and install Docker Desktop then run the following:
git clone https://github.com/black-parrot/black-parrot-sim.git
cd black-parrot-sim
make -C docker docker-image docker-run
# An alternate flow using docker-compose
# make -C docker docker-compose
Then follow the Tire Kick directions above starting with "cd black-parrot-sim" or the "Full" directions below. The repo directory will be mounted inside the container.
Build the toolchains
# Clone the latest repo
git clone https://github.com/black-parrot/black-parrot-sim.git
cd black-parrot-sim
# make prep is a meta-target which will build the RISC-V toolchains, programs and microcode
# needed for a full BlackParrot evaluation setup.
# Users who are changing code can use the targets in tagged submodules as appropriate
# For faster builds, make prep -j is parallelizable!
# To get started as fast as possible, use 'make prep_lite' which installs a minimal set of tools
# BSG users should instead use 'make prep_bsg', which sets up the bsg CAD environment
make prep
# Running your first test
make -C black-parrot/bp_top/syn build.sc sim.sc COSIM_P=1
Continuing Onward
Additional documentation is available in the main BlackParrot repo, in the Simulation Guide: BlackParrot