FireMarshal
This tool builds base images for several linux-based distros that work with qemu, spike, and firesim.
This is just a quick primer. To see full documentation, please see the official documentation: https://firemarshal.readthedocs.io/en/latest/index.html
Requirements
The easiest way to use Marshal is to run it via Chipyard (https://chipyard.readthedocs.io/en/latest/) or FireSim (https://docs.fires.im/en/latest/). However, this is not required. To run FireMarshal independently, you will need the following dependencies:
Standard Packages
centos-requirements.txt is a list of packages for centos7 that are needed by
marshal. You can install these with:
cat centos-requirements.txt | sudo xargs yum install -y
ubuntu-requirements.txt is a list of packages for Ubuntu 18.04 that are needed by marshal.
You can install these with:
cat ubuntu-requirements.txt | sudo xargs apt-get install -y
Package names may be different on other distributions.
Note for Ubuntu
The libguestfs-tools package (needed for the guestmount command) does not work out of the box on Ubuntu. See #30 for a workaround.
Python
This project was written for python 3.6. You can install all dependencies using:
pip3 install -r python-requirements.txt
RISC-V Tools
In addition to standard libraries, you will need a RISC-V compatible toolchain, the RISC-V isa simulator (spike).
See the Chipyard documentation for help setting up a known-good toolchain and environment.
Qemu
Qemu is the default simulator used by firemarshal. We require version v5.0.0 or greater. If you aren't using chipyard, you can get it from:
https://github.com/qemu/qemu/tree/v5.0.0
Basic Usage
If you only want to build bare-metal workloads, you can skip updating submodules. Otherwise, you should update the required submodules by running:
./init-submodules.sh
Building workloads:
./marshal build br-base.json
To run in qemu:
./marshal launch br-base.json
To install into FireSim (assuming you cloned this as a submodule of firesim or chipyard):
./marshal install br-base.json
Security Note
Be advised that FireMarshal will run initialization scripts provided by workloads. These scripts will have all the permissions your user has, be sure to read all workloads carefully before building them.
Releases
The master branch of this project contains the latest unstable version of FireMarshal. It should generally work correctly, but it may contain bugs or other inconsistencies from time to time. For stable releases, see the release git tags or github releases page.
Getting Help / Discussion:
- For general questions, help, and discussion: use the FireSim user forum: https://groups.google.com/forum/#!forum/firesim
- For bugs and feature requests: use the github issue tracker: https://github.com/firesim/FireMarshal/issues
- See CONTRIBUTING.md for information on how to contribute to the project