Skip to content

Latest commit

 

History

History
71 lines (50 loc) · 6.02 KB

VMSetup.md

File metadata and controls

71 lines (50 loc) · 6.02 KB
Raw

VM Setup Instructions

We provide a virtual machine (VM) which contains a pre-built/ready-to-use version of our entire toolchain. While it is slightly heavy (around 16GB) it is very easy to set up on your machine using QEMU (an open-source virtualizer available on all operating systems). You can download the VM image here.

This VM was originally set-up for the Dynamatic Reloaded tutorial given at the FPGA'24 conference in Monterey, California. You can use it to simply follow the tutorial (available in the repository's documentation) or as a starting point to use/modify Dynamatic in general.

Note

Note that Dynamatic's repository on the VM does not track the main branch but a branch specifically made for the tutorial. If you would like to build Dynamatic's latest version from the VM, you can checkout the main branch and use the regular build instructions from the top-level README to build the project's latest version.

System-based instructions

While the VM should work on all machines based on the x86_64 architecture, from our personal experience it works better on Linux than MacOS or Windows. Therefore, if you have the possibility, try to run the VM from Linux. While the VM can be emulated on MacOS on arm64, its performance is extremely degraded due to architecture emulation and so we do not recommend it. If you want to try anyway, you can follow the same instructions as for MacOS on x86_64 (just remove the -accel hvf part of the command to run the VM).

Linux

  1. Install the QEMU package on your machine following instructions here (many Linux distributions supported).

    • For Debian/Ubuntu, the option you should choose is apt-get install qemu-system.

  2. From a terminal, run the VM using

    qemu-system-x86_64 -accel kvm -m 8G -vga virtio -smp cores=4 -usb -device usb-tablet -display default,show-cursor=on /path/to/dynamatic-image.qcow2

MacOS

  1. Install the QEMU package on your machine using Homebrew by typing brew install qemu in a terminal.

    • If Homebrew is not installed on your machine, you can set it up with the following command.

      /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  2. From a terminal, run the VM using

    qemu-system-x86_64 -accel hvf -m 8G -vga virtio -smp cores=4 -usb -device usb-tablet -display default,show-cursor=on /path/to/dynamatic-image.qcow2

Windows

  1. Download the QEMU installer here.

  2. Run the executable and go through the simple installation process. Remember QEMU's install location; typically, it is C:\ProgramFiles\qemu.

  3. Enable Windows virtualization on your system.

    1. Click the search icon in the Windows tray.
    2. Type Turn Windows features on or off in the search bar and open the corresponding control panel page.
    3. Check the Virtual Machine Platform and Windows Hypervisor Platform boxes if they are not already checked (these names may be slightly different depending on the exact Windows version, anything to do with virtualization/hypervision must be checked).

  4. Click the search icon in the Windows tray and type Command Prompt to open-up a terminal. Then, cd to QEMU's install location and run the VM using

    qemu-system-x86_64 -accel whpx -m 8G -vga virtio -smp cores=4 -usb -device usb-tablet -display default,show-cursor=on \path\to\dynamatic-image.qcow2

Troubleshooting

  • Note that the window which opens when you run the qemu-system-x86_64 command may remain black and unresponsive for a couple minutes while the VM boots. Avoid resizing the window before the Ubuntu desktop appears, as it can cause graphical issues down the line.
  • By default the VM is allocated 8GB of RAM (-m 8G) and 4 CPU cores (-smp cores=4) on boot. You can modify those values if you wish to, but we do not recommend going for much less than these resources.
  • If you experience graphical or mouse cursor issues in the VM, try replacing the -vga virtio part of the command with -vga std. The latter may work better for your hardware.

Inside the VM

If everything went well, after launching the image you should see Ubuntu's splash screen and be dropped into the desktop directly. Below are some important things about the guest OS running on the VM.

  • The VM runs Ubuntu 22.04 LTS. Any kind of "system/program error" reported by Ubuntu can safely be dismissed or ignored.
  • The user on the VM is called dynamatic. The password is also dynamatic.
  • On the left bar you have icons corresponding to a file explorer, a terminal, a web browser (Firefox), and an IDE (VSCode) which opens Dynamatic by default.
    • There are a couple default Ubuntu settings you may want to modify for your convenience. You can open Ubuntu settings by clicking the three icons at the top right of the Ubuntu desktop and then selecting Settings.
    • You can change the default display resolution (1920x1080) by clicking on the Displays tab on the left, then selecting another resolution in the Resolution dropdown menu.
    • You can change the default keyboard layout (English US) by clicking on the Keyboard tab on the left. Next, click on the + button under Input Sources, then, in the pop-menu that appears, click on the three vertical dots icon, scroll down the list, and click Other. Find your keyboard layout in the list and double-click it to add it to the list of input sources. Finally, drag your newly added keyboard layout above English (US) to start using it.
  • When running commands for Dynamatic from the terminal, make sure you first cd to the dynamatic subfolder.
    • Since the user is also called dynamatic, pwd should display /home/dynamatic/dynamatic when you are in the correct folder.
    • You can run ./update-dynamatic.sh from the dynamatic subfolder to pull latest changes from the repository and automatically rebuild the project.