ECAD and Architecture Practical Classes

Setup instructions

The following sections give information on the various routes to running the labs:

• Route A: Virtual machine on your machine using VirtualBox
• Route A2: Virtual machine on Apple Silicon Mac using UTM/QEMU
• Route B: Using a department server via SSH
• Route C: Using the RISC-V tools via Docker

Route A: Ubuntu virtual machine on your x86 machine using VirtualBox

If you have a suitable machine and ability to download an 8GB file, we would recommend this route. A suitable machine is one of approximately the following spec:

• Intel/AMD CPU
• Virtualization support (VT-x or AMD-V) present and enabled in BIOS
• 4GB RAM (8GB or more strongly recommended)
• 24GB of free storage. It is possible to use USB storage or SD card but some USBs/SDs are very slow. Look for a drive with good IOPS (the 4K random write benchmark is a good indicator). If you are using this method, format to exFAT (Windows or Mac), ext3/ext4 (Linux), HFS+/APFS (Mac), NTFS (Windows) - other combinations are likely to have poor performance.
• 8GB of temporary storage (USB stick is fine, formatted something other than FAT32 which has a 4GB file size limit)
• A 64-bit host OS supported by VirtualBox (Windows, MacOS and Linux should be fine).

If you have a suitable machine, download a virtual machine image to your temporary storage (requires Raven to get the download link, but you can use a download manager or other tool on the link itself if you have connectivity problems).

Install VirtualBox

First download the most recent VirtualBox platform package. You don't need the `Extension Pack' (which has more restrictive licence conditions than the base package). If you are using a Linux distro with a package manager, instead install the VirtualBox package supplied by your distro (although if you find VirtualBox won't launch VMs, it may be worth upgrading to a newer release from the VirtualBox repositories linked from their webpage).

Install the downloaded VirtualBox on your machine.

Importing the VM

Make sure you have the ECAD-Labs .vmdk (disc image) and .vbox (VirtualBox configuration file). You will need to uncompress the .vmdk.xz you downloaded to make the .vmdk

Start VirtualBox, go to the Machine->Add menu and choose your .vbox file. You should now see an ECAD-Labs entry in the VM list on the left.

Next we need to add the disc. Click on Settings, find the Storage panel and inside the Controller: SATA. Select this. An 'add hard disk' button should appear to the right. Pick 'Choose existing disk' from the popup and select your .vmdk file.

If you have more than 4GB RAM, before booting we recommend increasing System->Base Memory to 6GB (on an 8GB laptop) or more if you have more than 8GB RAM. This will reduce your FPGA synthesis time. If you have only 4GB of RAM, don't open too many other programs while the VM is running otherwise your system will become slow and memory constrained. You should also allocate as many cores to the VM as you have in your machine.

Your VM should now be ready to boot. The login information for the VM is : login:ecad, password:ecad.

Start the VM and login to the desktop. Most of your work will be launched from the terminal which is reached via the start menu (bottom left), System Tools, QTerminal.

Guest additions

You will probably want to install VirtualBox's Guest Additions, which enable features such as resize of the VM's display, shared clipboard, shared folders, and so on. To do this, boot your VM to the desktop. Then on the menu of the VM window go to Devices->Insert Guest Additions CD Image. This should insert a virtual CD into the VM system that will automatically install the additions and their kernel module (when prompted the password is 'ecad').

If the installer doesn't start automatically, open the terminal and type:

sudo /media/ecad/VBox_GAs_7.1.0/VBoxLinuxAdditions.run

(the disc name 'VBox_GAs_7.1.0' may be different on your version - press Tab to autocomplete it).

Reboot the VM afterwards for them to take effect. You can then enable Devices->Shared clipboard->Bidirectional and enlarge your window to resize the screen.

Important: when rebooting the VM, don't simply hit the title bar 'X' or the 'power off' option in VirtualBox. This is equivalent to pulling out the power cable - it may leave the storage in an inconsistent state, lose files and possibly become unbootable. Instead, either use the 'reboot' or 'shutdown' menu inside the VM's desktop, or use VirtualBox's option to 'send the shutdown signal' or 'ACPI shutdown'.

Please note: you are responsible for taking backups of your files inside the VM, and should not assume the stability of the VM image (it may fail like any other machine).

USB setup (only if you have hardware)

Linux laptops

If you have a Linux laptop, to give VirtualBox access to your USB ports you will need to run the following outside of the VM:

sudo adduser $USER vboxusers

then reboot your laptop.

Windows laptops

On Windows, before starting the VM click on the 'ECAD-Labs' entry in the list of VMs and click on 'Settings'. Go to 'USB' and choose USB 1.1. OK the settings.

Now, find your VirtualBox install in Windows Explorer (probably C:\Program Files\Oracle\VirtualBox). Go to the drivers\USB\filter subdirectory. Right-click on VBoxUSBMon.inf (of type 'Setup Information') and select Install. Allow Windows to install it. Repeat the same for drivers\USB\device\VBoxUSB.inf.

Note that VirtualBox is incompatible with the USBpcap component of Wireshark, so if you have this you will need to uninstall it.

You should now be able to boot the VM with USB support.

Testing

See below for how to check the tools are correctly functioning.

Either you have not enabled VT-x, Intel Virtualisation Technology or similar) in your BIOS/UEFI settings, or Hyper-V (Windows' own hypervisor) is enabled. See this guide for details how to disable Hyper-V and enable VT-x.

On some versions of Windows, VirtualBox can coexist in a limited way with Hyper-V. If it doesn't work for you you may need to turn off Hyper-V. Hyper-V is used by Docker (our Route D) so you may need to change the setting if you switch rotues.

Everything is too small!

If you have a high density (HiDPI) screen, eg 4K, Apple Retina Display or similar, text in the LXDE desktop may be very small. In additional to scaling the VM window (making the pixels bigger - VirtualBox's 'scaled mode'), you can also configure the LXDE desktop for a HiDPI display. There isn't currently a simple setting for this but this answer outlines the procedure.

Keyboard driver

If you want to change to a different keyboard in the VM:

• Right-click on an empty space on the window bar at the bottom of the desktop
• Select 'add/remove panel items'
• In 'Panel Applets', click '+ Add'
• Double click 'Keyboard Layout Handler'
• A flag should appear on the bar at the bottom of the screen. Right click it, and click on 'Keyboard Layout Handler Settings'
• Untick 'Keep system layouts'
• Then you are free to add whatever keyboard layout you wish on the left side of the dialogue. Clicking on the flag will alternate between available layouts, or the dialogue will allow you to select a key combination.

Route A2: Virtual machine on Apple Silicon Macs

The Intel FPGA tools are only available for x86 Windows or Linux, which means they can't be run on Macs. If you have a Mac with an Apple Silicon (M1/M2/...) processor you won't be able to run the x86 VM, although Routes B/C/D should still be available to you. Alternatively we have come up with a way to run the FPGA tools in a 64-bit ARM (aarch64) VM under emulation, with some loss of performance over native x86. Being a pile of hacks we can only provide limited support for this, and would appreciate feedback. You can find the instructions for this here.

Route B: SSH access to a department server

SSH will give you access to command line tools running on a Linux server. It is also possible to use GUI tools like Modelsim and Quartus, but performance will be slow.

To get set up, make sure you have an SSH client on your computer. MacOS and Linux should already have the ssh command available in a terminal. For Windows 10 / 11, ssh is available in PowerShell, or you can install a third-party client.

First, need to register an SSH public key. Follow the instructions for setting up a key on the Student SSH server instructions to register your SSH key.

Once done, from a terminal type:

ssh [Javascript required]

which should connect to the ECAD lab server:

  $ ssh [Javascript required]
  The authenticity of host 'cl-teaching-ecad.cl.cam.ac.uk (128.232.113.137)' can't be established.
  ED25519 key fingerprint is SHA256:knlXiiu1OrSGlTrqMZCKai+DL2uEKnAJ1QRJLCctr5A.
  This key is not known by any other names
  Are you sure you want to continue connecting (yes/no/[fingerprint])? yes

Check the fingerprint you are shown matches the above, and if so type 'yes' at this prompt, which you should only get the first time. You should then enter the passphrase for your key:

  Warning: Permanently added 'cl-teaching-ecad.cl.cam.ac.uk' (ED25519) to the list of known hosts.

  Set up your SSH keys at https://sshkeys.cl.cam.ac.uk/

  Enter passphrase for key '/home/abc21/.ssh/id_rsa': 

When you successfully login:

  Welcome to Ubuntu 22.04.3 LTS (GNU/Linux 5.15.0-84-generic x86_64)

(more messages follow)

  abc21@cl-teaching-ecad:~$ 

At this prompt, every time you login you will need to add the ECAD labs tools to your PATH so we can execute them:

source /local/ecad/setup.bash

You should now be able to run tools, for example:

  abc21@cl-teaching-ecad:~$ source /local/ecad/setup.bash

  abc21@cl-teaching-ecad:~$ riscv32-unknown-elf-gcc --version
  riscv32-unknown-elf-gcc (GCC) 10.2.0
  Copyright (C) 2020 Free Software Foundation, Inc.
  This is free software; see the source for copying conditions.  There is NO
  warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

Route C: Docker

Docker is an environment for running software in containers - restricted environments where all the necessary software is packaged up together. Containers are more lightweight than virtual machines. In this case we run the RISC-V tools inside an Ubuntu container, which provides a Linux environment even if you might be running on a machine running a different operating system. The single container provides all the tools you will need for the RISC-V parts of this lab. We have not included the Modelsim Verilog simulator and Quartus FPGA tools for licensing reasons.

Setup instructions

To run the container you'll require a machine running Windows, MacOS or Linux.

First, install Docker. Docker Desktop is the recommended version on Windows or Mac, but the older Docker Toolbox should also work and works on more systems. Docker Engine is the recommended version on Linux (your distribution may provide Docker itself but it may be out of date). In Windows you may need to enable Windows features such as Hyper-V.

You can check Docker is successfully installed by opening a terminal window (PowerShell on Windows) and typing:

docker run hello-world

which should output:

  $ docker run hello-world
  Unable to find image 'hello-world:latest' locally
  latest: Pulling from library/hello-world
  0e03bdcc26d7: Pull complete 
  Digest: sha256:4cf9c47f86df71d48364001ede3a4fcd85ae80ce02ebad74156906caff5378bc
  Status: Downloaded newer image for hello-world:latest
  
  Hello from Docker!
  This message shows that your installation appears to be working correctly.
  
  To generate this message, Docker took the following steps:
   1. The Docker client contacted the Docker daemon.
   2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
      (amd64)
   3. The Docker daemon created a new container from that image which runs the
      executable that produces the output you are currently reading.
   4. The Docker daemon streamed that output to the Docker client, which sent it
      to your terminal.
  
  To try something more ambitious, you can run an Ubuntu container with:
   $ docker run -it ubuntu bash
  
  Share images, automate workflows, and more with a free Docker ID:
   https://hub.docker.com/
  
  For more examples and ideas, visit:
   https://docs.docker.com/get-started/
  
  

To run the Docker environment for the labs, first change directory in your terminal to a location on your machine where you want to save your work. For example on Windows:

mkdir C:\Users\me\ecad-labs
cd C:\Users\me\ecad-labs

(instead of C:\Users\me on Windows, on Mac it might be /Users/me and Linux /home/me, where 'me' is the account name on your machine. You are of course free to put it whereever you like on your machine, but we suggest avoiding any folder with spaces in the name.)

Then, on Mac and Linux:

docker run -it -v $(pwd):/home/ecad ucamcstecad/ecad-riscv:latest

or Windows PowerShell:

docker run -it -v ${PWD}:/home/ecad ucamcstecad/ecad-riscv:latest

The first time you run this, it will download the Docker image to your machine and launch it. On subsequent runs it will use a cached image, so can be done offline.

This will launch a Linux bash shell in the /home/ecad folder (the number after @ may vary):

ecad@61f61f4ed56e:~$

The /home/ecad directory in the container is linked to the location you ran the 'docker run' command from, C:\Users\me\ecad-labs in this example. This means that you can see your Windows/Mac/etc files inside the Linux environment.

Inside this environment you can then run the commands we describe in the labs.

Important note: Docker containers are designed to be immutable, that is they don't retain state when you quit them. Things you save in the /home/ecad folder will be retained, but every time you start the container you'll get a fresh instance of things outside. Should you wish to modify the container, for example install extra Ubuntu packages, you'll need to commit the changes to a new container before closing it, essentially making a copy, and then start that container next time. To do this you need the image ID which is the number between ecad@ and :~$ on the prompt (61f61f4ed56e in this example), and run the commands in a second terminal:

$ docker commit 61f61f4ed56e my-ecad-labs:v1

and next time you want to start the container, instead of launching ucamcstecad/ecad-riscv do:

docker run -it -v $(pwd):/home/ecad my-ecad-labs:v1

To further update this state, you can repeat the process with the image ID of this new container.

Windows note: On Windows, file permissions prevent SSH from working inside the container. Therefore we recommend installing Git BASH and running your git and ssh-keygen commands in a separate PowerShell outside the Docker environment. Additionally, you will need to share your working directory (eg C:\Users\me\ecad-labs) by going into Docker's settings, then Resources, File Sharing and adding this directory. (If this option is not present, don't worry - the setting is only needed on some installations of Docker).