QEMU Networking using slirp and vdeplug4

.gitignore

@@ -5,3 +5,4 @@ wlutil/_command.sh
 .doit.db*
 marshal-config.yaml
 .ropeproject
+dependencies

README.md

@@ -2,62 +2,44 @@ FireMarshal
 ==================================
 
 This tool builds base images for several linux-based distros that work with qemu,
-spike, and firesim.
+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
+# Setup
+
 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:
+(https://docs.fires.im/en/latest/). However, this is not required. 
+
+Run the following script to install all of FireMarshal's dependencies (standard packages from apt/yum, python libraries, open-source packages, submodules):
 
-## 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
+./install/marshal-dependencies.sh
 ```
 
-``ubuntu-requirements.txt`` is a list of packages for Ubuntu 18.04 that are needed by marshal.
-You can install these with:
+Note that this script downloads dependencies to `install/dependencies` and installs them at the path pointed to by the `RISCV` environment variable. Thus, the script requires `RISCV` to be set and FireMarshal expects `PATH` to contain the path it points to (Chipyard/FireSim already do this).
+
+Running bare-metal workloads requires a minimal set of dependencies. You can install just these by passing the `-b` flag as follows:
+
 ```
-cat ubuntu-requirements.txt | sudo xargs apt-get install -y
+./install/marshal-dependencies.sh -b
 ```
 
-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
 https://github.com/firesim/firesim-software/issues/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).
+In addition to the dependencies installed above, you will need a RISC-V compatible toolchain, the RISC-V isa simulator (spike). This is already installed by Chipyard/FireSim.
 
 See the [Chipyard documentation](https://chipyard.readthedocs.io/en/latest/Chipyard-Basics/Initial-Repo-Setup.html#building-a-toolchain)
 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:
 
@@ -67,7 +49,7 @@ To run in qemu:
 
     ./marshal launch br-base.json
 
-To install into FireSim (assuming you cloned this as a submodule of firesim or chipyard):
+To install into FireSim (assuming you cloned this as a submodule of FireSim or Chipyard):
 
     ./marshal install br-base.json
 

boards/default/distros/fedora/fedora.py

@@ -7,6 +7,8 @@
 serviceTemplate = """[Unit]
 Requires=multi-user.target
 After=multi-user.target
+Requires=network-online.target
+After=network-online.target
 Before=firesim.target
 Wants=firesim.target
 

boards/default/distros/fedora/overlay/etc/systemd/system/firesim.service

@@ -0,0 +1,11 @@
+[Unit]
+Requires=multi-user.target
+After=multi-user.target
+Requires=network-online.target
+After=network-online.target
+Before=firesim.target
+Wants=firesim.target
+
+[Service]
+ExecStart=/etc/firesim/firesim.sh 
+StandardOutput=journal+console

boards/firechip/base-workloads/br-base/overlay/etc/init.d/S40network

@@ -2,37 +2,43 @@
 #
 # Start the network....
 #
-
 # Debian ifupdown needs the /run/network lock directory
 mkdir -p /run/network
 
+# Write DNS to /etc/resolv.conf
+resolvconf_file="/etc/resolv.conf"
+rm -f $resolvconf_file
+echo "nameserver 172.16.1.3" > $resolvconf_file
+
+# mac address of NIC at eth0 decides ip address we'd like to use
+ifname=eth0
+read _ addr _ _ <<< $(/sbin/ip link | /bin/grep -A 1 "$ifname" | /usr/bin/tail -1)
+# Extract the bottom 2 bytes of mac addr
+IFS=: read -r _ _ _ _ machigh maclow <<< $addr
+
 case "$1" in
-  start)
-	printf "Starting network: "
-	/sbin/ifup -a
-	ifname=eth0
-	if test -r "/sys/class/net/${ifname}/address" ; then
-		/sbin/ip link set dev "$ifname" up &&
-		IFS=: read -r _ _ _ _ machigh maclow < "/sys/class/net/${ifname}/address" &&
-		/sbin/ip addr add "172.16.$((16#$machigh)).$((16#$maclow))/16" dev "$ifname"
-	fi
-#	/sbin/ifup eth0
-	[ $? = 0 ] && echo "OK" || echo "FAIL"
-	;;
-  stop)
-	printf "Stopping network: "
-	/sbin/ifdown -a
-#	/sbin/ifdown eth0
-	[ $? = 0 ] && echo "OK" || echo "FAIL"
-	;;
-  restart|reload)
-	"$0" stop
-	"$0" start
-	;;
-  *)
-	echo "Usage: $0 {start|stop|restart}"
-	exit 1
+	start)
+		printf "Starting network: "
+	# Use sed to substitute target address 172.16.machigh.maclow for the first interface (eth0) in /etc/network/interfaces
+	/bin/sed -i -e "1,/^address/{s/^address.*/address 172.16.$((16#$machigh)).$((16#$maclow))/;}" /etc/network/interfaces
+        sbin/ifup -a
+        [ $? = 0 ] && echo "OK" || echo "FAIL"
+        ;;
+    stop)
+        printf "Stopping network: "
+        /sbin/ifdown -a
+	# Not functionalyl necessary, substitute "firemarshal_ip_addr_uninitialized" for eth0 in /etc/network/interfaces to make the file understandable for users
+        /bin/sed -i -e "1,/^address/{s/^address.*/address firemarshal_ip_addr_uninitialized/;}" /etc/network/interfaces
+        [ $? = 0 ] && echo "OK" || echo "FAIL"
+        ;;
+    restart|reload)
+        "$0" stop
+        "$0" start
+        ;;
+    *)
+        echo "Usage: $0 {start|stop|restart}"
+        exit 1
+
 esac
 
 exit $?
-

boards/firechip/base-workloads/br-base/overlay/etc/network/interfaces

@@ -1,4 +1,10 @@
-
+# marshal requires eth0 to be the first interface in this file, please add other interfaces below it
 auto lo
 iface lo inet loopback
 
+auto eth0
+iface eth0 inet static
+address firemarshal_ip_addr_uninitialized
+netmask 255.255.0.0
+gateway 172.16.0.1
+dns-nameservers 172.16.1.3

boards/firechip/base-workloads/fedora-base/overlay/etc/firesim/ifcfg-static

@@ -2,3 +2,5 @@ DEVICE=eth0
 BOOTPROTO=static
 ONBOOT=on
 PREFIX=16
+PEERDNS=yes
+DNS1=172.16.1.3

boards/firechip/base-workloads/fedora-base/overlay/etc/firesim/network-static

@@ -0,0 +1,3 @@
+NETWORKING=yes
+NETWORKING_IPV6=no
+GATEWAY=172.16.0.1

boards/firechip/base-workloads/fedora-base/overlay/etc/firesim/start-firesim-network.sh

@@ -12,6 +12,8 @@ case "$macpref" in
                 maclow=$(echo $mac | cut -c 16-17 -)
                 cp /etc/firesim/ifcfg-static /etc/sysconfig/network-scripts/ifcfg-eth0
                 echo IPADDR=172.16.$((16#$machigh)).$((16#$maclow)) >> /etc/sysconfig/network-scripts/ifcfg-eth0
+                echo default via 172.16.0.1 dev eth0 > /etc/sysconfig/network-scripts/route-eth0
+                cp /etc/firesim/network-static /etc/sysconfig/network
                 ;;
         "52:54:00")
                 echo "this looks like not FireSim. exiting"

docs/source/Tutorials/paralleljobs.rst

@@ -4,7 +4,7 @@ Parallel Jobs
 ======================
 ``example-workloads/parallelJobs.yaml``
 
-FireMarshal is capable of running multiple jobs in parallel. To understand how this feature works, let's use the ``parallelJobs.yaml`` workload as an example.
+FireMarshal is capable of running multiple networked jobs in parallel. To understand how this feature works, let's use the ``parallelJobs.yaml`` workload as an example.
 
 .. include:: ../../../example-workloads/parallelJobs.yaml
   :code: json
@@ -28,7 +28,23 @@ The default login details for all workloads are:
 
 ``Password:`` ``firesim``
 
-Once logged in, you can run commands in the terminal. To exit, use:
+Once logged in, you can run commands in the terminal. 
+
+FireMarshal uses a Virtual Distributed Ethernet (VDE) network with a gateway at ``172.16.0.1`` and DNS nameserver at ``172.16.1.3``. It assigns IP addresses starting with ``172.16.0.2``. 
+
+We expect the root workload to have an IP address of ``172.16.0.2``. We can check the IP address assigned to interface ``eth0`` with:
+
+::
+
+  ip addr show eth0
+
+We can also test conncectivity to the internet with:
+
+::
+
+  wget -S fires.im
+
+To exit, use:
 
 ::
 
@@ -61,28 +77,51 @@ For instance, attach to job ``j0``, using:
 
   screen -r parallelJobs-j0
 
+You need to login with the the details provided above.
+
+We expect job ``j0`` to have IP address ``172.16.0.2`` and job ``j1`` to have IP address ``172.16.0.3``. Let's test these out!
+
+Inside job ``j0``, run:
+
+::
+
+  ip addr show eth0
+
 
 To detach from inside the screen session, use ``ctrl-a`` then ``ctrl-d``.
 
 
-Similarly, attach to job ``j1``, using:
+Again, we can attach to job ``j1``, using:
 
 ::
 
   screen -r parallelJobs-j1
 
+Similarly, we test the IP address of job ``j1`` with:
+
+::
+
+  ip addr show eth0
+
+Jobs ``j0`` and ``j1`` should be able to communicate with each other over the network. We can try this feature by pinging ``j0 (172.16.0.2)`` from ``j1``:
+
+::
+
+  ping 172.16.0.2
+
+You should see the command print the result of sending and receiving packets. We can terminate this command with ``Ctrl/Command + C``.
 
-Login (with the details provided above) and then use the ``poweroff`` command to shut job ``j1`` down.
+Now, use the ``poweroff`` command to shut job ``j1`` down.
 
 
-Now re-attach to job ``j0``, using:
+Then, re-attach to job ``j0``, using:
 
 ::
 
   screen -r parallelJobs-j0
 
 
-Login (with the details provided above) and then use the ``poweroff`` command to shut job ``j0`` down.
+Again, use the ``poweroff`` command to shut job ``j0`` down.
 
 FireMarshal also logs ``stdout`` and ``stderr`` to a ``uartlog`` file for each workload. These files can be found inside the corresponding workload output directory inside ``runOutputs``. The path to this directory will be output by the ``launch`` command. For instance, a workload output directory for the launched ``parallelJobs`` workload would be called ``parallelJobs-launch-YYYY-MM-DD--HH-MM-SS-<HASH>``.  
 

docs/source/commands.rst

@@ -83,7 +83,7 @@ Launch all jobs in the workload. Jobs will be run sequentially. See the
 ``-j --job``
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 In workloads with multiple jobs, you can specify which job(s) to launch.
-FireMarshal supports running multiple jobs concurrently but does not support networked jobs yet. Jobs are identified by their ``name`` attribute. Multiple ``-j``
+FireMarshal supports running multiple networked jobs concurrently. Jobs are identified by their ``name`` attribute. Multiple ``-j``
 options may be passed to invoke multiple jobs. Use ``--all`` to launch all jobs
 in the workload. If neither ``--job`` nor ``--all`` are provided, the root
 workload will be run. The root workload is the parent of all the jobs (i.e. the