|
|
|
---
|
|
|
|
title: BXE FireSim Documentation - Docker Image
|
|
|
|
version: v2.0.0
|
|
|
|
firesim:
|
|
|
|
version: v1.18.0
|
|
|
|
url: https://github.com/firesim/firesim/tree/1.16.0
|
|
|
|
docs-url: https://docs.fires.im/en/stable/Building-a-FireSim-Xclbin.html
|
|
|
|
chipyard:
|
|
|
|
version: 766ea73
|
|
|
|
url: https://github.com/ucb-bar/chipyard/tree/766ea735accefb531309b5be95313e02ce182127
|
|
|
|
firemarshal:
|
|
|
|
version: b014183
|
|
|
|
url: https://github.com/firesim/FireMarshal/tree/b014183ac6afed7fe1aca89fa010be8d13ad4079
|
|
|
|
aro-cn: D2021-2106030006
|
|
|
|
---
|
|
|
|
|
|
|
|
# {height=24px} BXE FireSim - Docker Image
|
|
|
|
|
|
|
|
We provide a Docker image setup with the Chipyard and FireMarshal environment that is used within BXE FireSim to build designs. This guide will show you how to download the Docker image, and build custom designs with Chipyard's[^2] metasimulation environment.
|
|
|
|
|
|
|
|
This work was funded by the iARPA AGILE Program. [^1]
|
|
|
|
|
|
|
|
[[_TOC_]]
|
|
|
|
|
|
|
|
# Prerequisites
|
|
|
|
|
|
|
|
## Installing Docker
|
|
|
|
|
|
|
|
<img src="https://www.docker.com/wp-content/uploads/2022/03/vertical-logo-monochromatic.png" align="right" width="250px" alt="Alveo U250">
|
|
|
|
|
|
|
|
The material in this document requires the use of [Docker](https://www.docker.com/). Either one of the following options will work:
|
|
|
|
|
|
|
|
- Access to a server with Docker installed
|
|
|
|
|
|
|
|
- Make sure your user account has been added to the `docker` group
|
|
|
|
|
|
|
|
- Use [Docker Desktop](https://docs.docker.com/get-docker/) on your local machine
|
|
|
|
|
|
|
|
> [!WARNING] Apple Silicon
|
|
|
|
> If you use Apple Silicon (`aarch64`-based CPU), builds and simulations are prohibitively slow.
|
|
|
|
>
|
|
|
|
> `x86-64` processors are HIGHLY recommended.
|
|
|
|
|
|
|
|
## Pulling the Docker image
|
|
|
|
|
|
|
|
Docker images contain all of the files and binaries needed to run a particular task. You can think of Docker images as virtual machine snapshots. Our container registry has a collection of these images. Much like Git, these _tags_ are images that contain different files for different projects. We'll pull the `latest` tag, as shown below:
|
|
|
|
|
|
|
|
```
|
|
|
|
docker pull socks.lbl.gov:4567/cag/bxe
|
|
|
|
```
|
|
|
|
|
|
|
|
## Running a Docker container
|
|
|
|
|
|
|
|
Once you've pulled a Docker image, you can run within a container. You can think of containers as the virtual machine that's running the image you pulled. When a container is initialized and run, it's given a unique hash and a unique string name. When you want to access the container, you refer to its unique hash/string. You can also give your container a unique name, as demonstrated below:
|
|
|
|
|
|
|
|
> **NOTE:** `--privileged` is only required when using FireMarshal.
|
|
|
|
|
|
|
|
- Running a Docker container interactively
|
|
|
|
- This runs the Docker container and attaches the console of your container
|
|
|
|
```
|
|
|
|
docker run [--privileged] [--name CUSTOM_CONTAINER_NAME] -it socks.lbl.gov:4567/cag/bxe/firesim
|
|
|
|
```
|
|
|
|
|
|
|
|
- Running a Docker container and attaching later
|
|
|
|
- You can run a Docker container in the background and attach to it
|
|
|
|
```
|
|
|
|
docker run [--privileged] [--name CUSTOM_CONTAINER_NAME] socks.lbl.gov:4567/cag/bxe/firesim
|
|
|
|
docker attach [HASHID/STRINGID/CUSTOM_CONTAINER_NAME]
|
|
|
|
```
|
|
|
|
|
|
|
|
### Mounting Host Directories in Docker containers
|
|
|
|
|
|
|
|
You can mount directories from your host machine within your container with the `-v [HOSTDIR]:[CONTAINERDIR]` flag. In this example, we want to mount `/tmp/mpoint` from our host machine to `/app` in the container.
|
|
|
|
|
|
|
|
```
|
|
|
|
docker run \
|
|
|
|
[--privileged] [--name CUSTOM_CONTAINER_NAME] \
|
|
|
|
-it \
|
|
|
|
-v /tmp/mpoint:/app \
|
|
|
|
socks.lbl.gov:4567/cag/bxe/firesim
|
|
|
|
```
|
|
|
|
|
|
|
|
Any changes made in `/app` in the Docker container are reflected in `/tmp/mpoint` on the host. You can mount multiple directories with multiple `-v [HOSTDIR]:[CONTAINERDIR]` flags with the different mounts.``
|
|
|
|
|
|
|
|
# Initializing the Chipyard and FireMarshal Environment
|
|
|
|
|
|
|
|
Once you've run and attached to your Docker container, you should see the following output on your console:
|
|
|
|
|
|
|
|
```
|
|
|
|
(base) root@[HASHID]:~/firesim#
|
|
|
|
```
|
|
|
|
|
|
|
|
Run the following commands to set up the Chipyard and FireMarshal environment:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
conda activate firesim
|
|
|
|
source sourceme-manager.sh --skip-ssh-setup
|
|
|
|
```
|
|
|
|
|
|
|
|
You should see the following output on your console:
|
|
|
|
|
|
|
|
```
|
|
|
|
(base) bxeuser@[HASHID]:~/firesim$ conda activate firesim
|
|
|
|
(firesim) bxeuser@[HASHID]:~/firesim$ source sourceme-manager.sh --skip-ssh-setup
|
|
|
|
(/home/bxeuser/firesim/.conda-env) bxeuser@[HASHID]:~/firesim$
|
|
|
|
```
|
|
|
|
|
|
|
|
You are now ready to build RTL with Chipyard and build software with FireMarshal.
|
|
|
|
# File and Directory Structure
|
|
|
|
|
|
|
|
## FireSim
|
|
|
|
|
|
|
|
Environment Variable: `$FIRESIM_ROOT`
|
|
|
|
|
|
|
|
Directory Path: `~/firesim`
|
|
|
|
|
|
|
|
Files/Directories of Note:
|
|
|
|
|
|
|
|
- `deploy`: This is where the FireSim configuration YAML is located, specifically `config_build_recipes.yaml`, `config_build.yaml`, `config_hwdb.yaml`, and `config_runtime.yaml`.
|
|
|
|
|
|
|
|
|
|
|
|
## Chipyard
|
|
|
|
|
|
|
|
Environment Variable: `$CHIPYARD_ROOT`
|
|
|
|
|
|
|
|
Directory Path: `~/firesim/target-design/chipyard`
|
|
|
|
|
|
|
|
Files/Directories of Note:
|
|
|
|
|
|
|
|
- `generators`: This is a collection of all of the source code required hardware generators contained within Chipyard. This includes Rocket Chip (SoC generator), Rocket/BOOM/CVA6 (Processors), Constellation (NoC Generator), among many more. This is the place to put any custom hardware for your design.
|
|
|
|
|
|
|
|
- `generators/chipyard/src/main/scala/config`: This is the list of available Chipyard Mixins that Chipyard uses to generate hardware designs.
|
|
|
|
|
|
|
|
- `generators/chipyard/src/main/scala/DigitalTop.scala`: This file controls the top level dependencies for the RocketChip SoC generators. If you add any custom hardware, make sure to add your hardware Scala Trait to the `DigitalTop` module in `DigitalTop.scala`.
|
|
|
|
|
|
|
|
- `build.sbt`: This file manages the relative locations of all of the Scala packages needed to run the Chipyard generator. If you add any custom hardware as it's own Scala package, make sure to add its path to this file, as well as making it a dependency for the `chipyard` package.
|
|
|
|
|
|
|
|
- `sims/verilator`: This is where you run `make` with the config flag of your custom hardware. All Verilog is generated here as well.
|
|
|
|
|
|
|
|
## FireMarshal
|
|
|
|
|
|
|
|
Environment Variable: N/A
|
|
|
|
|
|
|
|
Directory Path: `$CHIPYARD_ROOT/software/firemarshal`
|
|
|
|
|
|
|
|
Files/Directories of Note:
|
|
|
|
|
|
|
|
- `example-workloads`: This directory contains examples of using FireMarshal for different OS or bare-metal based systems.
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
[^1]: This research is based upon work supported by the Office of the Director of National Intelligence (ODNI), Intelligence Advanced Research Projects Activity (IARPA), through the Advanced Graphical Intelligence Logical Computing Environment (AGILE) research program, under Army Research Office (ARO) contract number D2021-2106030006. The views and conclusions contained herein are those of the authors and should not be interpreted as necessarily representing the official policies or endorsements, either expressed or implied, of the ODNI, IARPA, ARO, or the U.S. Government.
|
|
|
|
|
|
|
|
[^2]: [Chipyard](https://chipyard.readthedocs.io/en/stable/) is a framework for designing and evaluating full-system hardware using agile teams. It is composed of a collection of tools and libraries designed to provide an integration between open-source and commercial tools for the development of systems-on-chip. |
|
|
|
---
|
|
|
|
title: BXE FireSim Documentation - Docker Image
|
|
|
|
version: v2.0.0
|
|
|
|
firesim:
|
|
|
|
version: v1.18.0
|
|
|
|
url: https://github.com/firesim/firesim/tree/1.16.0
|
|
|
|
docs-url: https://docs.fires.im/en/stable/Building-a-FireSim-Xclbin.html
|
|
|
|
chipyard:
|
|
|
|
version: 766ea73
|
|
|
|
url: https://github.com/ucb-bar/chipyard/tree/766ea735accefb531309b5be95313e02ce182127
|
|
|
|
firemarshal:
|
|
|
|
version: b014183
|
|
|
|
url: https://github.com/firesim/FireMarshal/tree/b014183ac6afed7fe1aca89fa010be8d13ad4079
|
|
|
|
aro-cn: D2021-2106030006
|
|
|
|
---
|
|
|
|
|
|
|
|
# {height=24px} BXE FireSim - Docker Image
|
|
|
|
|
|
|
|
We provide a Docker image setup with the Chipyard and FireMarshal environment that is used within BXE FireSim to build designs. This guide will show you how to download the Docker image, and build custom designs with Chipyard's[^2] metasimulation environment.
|
|
|
|
|
|
|
|
This work was funded by the iARPA AGILE Program. [^1]
|
|
|
|
|
|
|
|
[[_TOC_]]
|
|
|
|
|
|
|
|
# Prerequisites
|
|
|
|
|
|
|
|
## Installing Docker
|
|
|
|
|
|
|
|
<img src="https://www.docker.com/wp-content/uploads/2022/03/vertical-logo-monochromatic.png" align="right" width="250px" alt="Alveo U250">
|
|
|
|
|
|
|
|
The material in this document requires the use of [Docker](https://www.docker.com/). Either one of the following options will work:
|
|
|
|
|
|
|
|
- Access to a server with Docker installed
|
|
|
|
|
|
|
|
- Make sure your user account has been added to the `docker` group
|
|
|
|
|
|
|
|
- Use [Docker Desktop](https://docs.docker.com/get-docker/) on your local machine
|
|
|
|
|
|
|
|
> :warning: If you use Apple Silicon (`aarch64`-based CPU), builds and simulations are prohibitively slow.
|
|
|
|
>
|
|
|
|
> `x86-64` processors are HIGHLY recommended.
|
|
|
|
|
|
|
|
## Pulling the Docker image
|
|
|
|
|
|
|
|
Docker images contain all of the files and binaries needed to run a particular task. You can think of Docker images as virtual machine snapshots. Our container registry has a collection of these images. Much like Git, these _tags_ are images that contain different files for different projects. We'll pull the `latest` tag, as shown below:
|
|
|
|
|
|
|
|
```
|
|
|
|
docker pull socks.lbl.gov:4567/cag/bxe
|
|
|
|
```
|
|
|
|
|
|
|
|
## Running a Docker container
|
|
|
|
|
|
|
|
Once you've pulled a Docker image, you can run within a container. You can think of containers as the virtual machine that's running the image you pulled. When a container is initialized and run, it's given a unique hash and a unique string name. When you want to access the container, you refer to its unique hash/string. You can also give your container a unique name, as demonstrated below:
|
|
|
|
|
|
|
|
> :exclamation: **NOTE:** `--privileged` is only required when using FireMarshal.
|
|
|
|
|
|
|
|
- Running a Docker container interactively
|
|
|
|
- This runs the Docker container and attaches the console of your container
|
|
|
|
```
|
|
|
|
docker run [--privileged] [--name CUSTOM_CONTAINER_NAME] -it socks.lbl.gov:4567/cag/bxe/firesim
|
|
|
|
```
|
|
|
|
|
|
|
|
- Running a Docker container and attaching later
|
|
|
|
- You can run a Docker container in the background and attach to it
|
|
|
|
```
|
|
|
|
docker run [--privileged] [--name CUSTOM_CONTAINER_NAME] socks.lbl.gov:4567/cag/bxe/firesim
|
|
|
|
docker attach [HASHID/STRINGID/CUSTOM_CONTAINER_NAME]
|
|
|
|
```
|
|
|
|
|
|
|
|
### Mounting Host Directories in Docker containers
|
|
|
|
|
|
|
|
You can mount directories from your host machine within your container with the `-v [HOSTDIR]:[CONTAINERDIR]` flag. In this example, we want to mount `/tmp/mpoint` from our host machine to `/app` in the container.
|
|
|
|
|
|
|
|
```
|
|
|
|
docker run \
|
|
|
|
[--privileged] [--name CUSTOM_CONTAINER_NAME] \
|
|
|
|
-it \
|
|
|
|
-v /tmp/mpoint:/app \
|
|
|
|
socks.lbl.gov:4567/cag/bxe/firesim
|
|
|
|
```
|
|
|
|
|
|
|
|
Any changes made in `/app` in the Docker container are reflected in `/tmp/mpoint` on the host. You can mount multiple directories with multiple `-v [HOSTDIR]:[CONTAINERDIR]` flags with the different mounts.``
|
|
|
|
|
|
|
|
# Initializing the Chipyard and FireMarshal Environment
|
|
|
|
|
|
|
|
Once you've run and attached to your Docker container, you should see the following output on your console:
|
|
|
|
|
|
|
|
```
|
|
|
|
(base) root@[HASHID]:~/firesim#
|
|
|
|
```
|
|
|
|
|
|
|
|
Run the following commands to set up the Chipyard and FireMarshal environment:
|
|
|
|
|
|
|
|
```bash
|
|
|
|
conda activate firesim
|
|
|
|
source sourceme-manager.sh --skip-ssh-setup
|
|
|
|
```
|
|
|
|
|
|
|
|
You should see the following output on your console:
|
|
|
|
|
|
|
|
```
|
|
|
|
(base) bxeuser@[HASHID]:~/firesim$ conda activate firesim
|
|
|
|
(firesim) bxeuser@[HASHID]:~/firesim$ source sourceme-manager.sh --skip-ssh-setup
|
|
|
|
(/home/bxeuser/firesim/.conda-env) bxeuser@[HASHID]:~/firesim$
|
|
|
|
```
|
|
|
|
|
|
|
|
You are now ready to build RTL with Chipyard and build software with FireMarshal.
|
|
|
|
# File and Directory Structure
|
|
|
|
|
|
|
|
## FireSim
|
|
|
|
|
|
|
|
Environment Variable: `$FIRESIM_ROOT`
|
|
|
|
|
|
|
|
Directory Path: `~/firesim`
|
|
|
|
|
|
|
|
Files/Directories of Note:
|
|
|
|
|
|
|
|
- `deploy`: This is where the FireSim configuration YAML is located, specifically `config_build_recipes.yaml`, `config_build.yaml`, `config_hwdb.yaml`, and `config_runtime.yaml`.
|
|
|
|
|
|
|
|
|
|
|
|
## Chipyard
|
|
|
|
|
|
|
|
Environment Variable: `$CHIPYARD_ROOT`
|
|
|
|
|
|
|
|
Directory Path: `~/firesim/target-design/chipyard`
|
|
|
|
|
|
|
|
Files/Directories of Note:
|
|
|
|
|
|
|
|
- `generators`: This is a collection of all of the source code required hardware generators contained within Chipyard. This includes Rocket Chip (SoC generator), Rocket/BOOM/CVA6 (Processors), Constellation (NoC Generator), among many more. This is the place to put any custom hardware for your design.
|
|
|
|
|
|
|
|
- `generators/chipyard/src/main/scala/config`: This is the list of available Chipyard Mixins that Chipyard uses to generate hardware designs.
|
|
|
|
|
|
|
|
- `generators/chipyard/src/main/scala/DigitalTop.scala`: This file controls the top level dependencies for the RocketChip SoC generators. If you add any custom hardware, make sure to add your hardware Scala Trait to the `DigitalTop` module in `DigitalTop.scala`.
|
|
|
|
|
|
|
|
- `build.sbt`: This file manages the relative locations of all of the Scala packages needed to run the Chipyard generator. If you add any custom hardware as it's own Scala package, make sure to add its path to this file, as well as making it a dependency for the `chipyard` package.
|
|
|
|
|
|
|
|
- `sims/verilator`: This is where you run `make` with the config flag of your custom hardware. All Verilog is generated here as well.
|
|
|
|
|
|
|
|
## FireMarshal
|
|
|
|
|
|
|
|
Environment Variable: N/A
|
|
|
|
|
|
|
|
Directory Path: `$CHIPYARD_ROOT/software/firemarshal`
|
|
|
|
|
|
|
|
Files/Directories of Note:
|
|
|
|
|
|
|
|
- `example-workloads`: This directory contains examples of using FireMarshal for different OS or bare-metal based systems.
|
|
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
[^1]: This research is based upon work supported by the Office of the Director of National Intelligence (ODNI), Intelligence Advanced Research Projects Activity (IARPA), through the Advanced Graphical Intelligence Logical Computing Environment (AGILE) research program, under Army Research Office (ARO) contract number D2021-2106030006. The views and conclusions contained herein are those of the authors and should not be interpreted as necessarily representing the official policies or endorsements, either expressed or implied, of the ODNI, IARPA, ARO, or the U.S. Government.
|
|
|
|
|
|
|
|
[^2]: [Chipyard](https://chipyard.readthedocs.io/en/stable/) is a framework for designing and evaluating full-system hardware using agile teams. It is composed of a collection of tools and libraries designed to provide an integration between open-source and commercial tools for the development of systems-on-chip. |
