commit e036c194ed46b001ca88fa6231a0cc7b35313566 Author: Movitz Aaron Date: Sat Oct 24 15:53:57 2026 +0100 Add EMBS remote access setup: embs.sh, README guide, VLAB docs diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..e5ee812 --- /dev/null +++ b/.gitignore @@ -0,0 +1,15 @@ +# Never commit VLAB keys +*.vlabkey +*.key + +# macOS +.DS_Store + +# VLAB frame captures +capture_*.jpg + +# Xilinx build output, if you ever copy a project in +*.Xil/ +*.jou +*.log +*.str diff --git a/README.md b/README.md new file mode 100644 index 0000000..763a014 --- /dev/null +++ b/README.md @@ -0,0 +1,175 @@ +# Running Vivado & Vitis on your own Mac (EMBS) + +Vivado and Vitis have **no macOS version at all**, so you cannot install them on a Mac. Instead we +run them on the University's Linux server (`csteach0.york.ac.uk`) and have their windows drawn on +the Mac by **XQuartz**. That is the whole trick. + +**Time: about 15 minutes. Space used on your Mac: ~200 MB** (XQuartz only — the 60 GB of Xilinx +tools lives on the server, not on you). + +--- + +## Before you start + +You need: + +- [ ] Your **University IT account** and your **ITS username** (looks like `abc500`). +- [ ] Access to the **off-campus SSH gateway** (`ssh.york.ac.uk`). If you can't get in even with + the right password, ask IT Services or the module staff. +- [ ] **XQuartz** — free, installed in step 3. +- [ ] *Later, only for the FPGA boards:* a **VLAB keyfile** from Ian. You do **not** need this to + run Vivado — only to program a real board. + +You do **not** need to download Vivado, and you do **not** need a licence file. + +--- + +## Step 1 — Tell SSH how to reach the server + +The server is behind the University firewall, so you must hop through the IT Services gateway. +Open (or create) `~/.ssh/config` and add the following, replacing `abc500` with **your own** ITS +username: + +``` +Host ssh.york.ac.uk + User abc500 + +Host csteach0.york.ac.uk + User abc500 + ProxyCommand ssh -A -T -o Compression=no ssh.york.ac.uk -W %h:%p +``` + +Then lock down the permissions: + +```bash +chmod 600 ~/.ssh/config +``` + +## Step 2 — Make an SSH key and copy it to the server + +```bash +ssh-keygen -t ed25519 # just press Enter for every prompt +ssh-copy-id csteach0.york.ac.uk +``` + +`ssh-copy-id` asks for your password **several times** — once for the gateway, then for the +server. That is expected. + +## Step 3 — Install XQuartz + +```bash +brew install --cask xquartz +``` + +No Homebrew? Download it from instead. + +**Then log out and back in.** If `echo $DISPLAY` is still empty afterwards, don't worry about it +— the script in step 4 sets it for you. + +## Step 4 — Get the connection script + +```bash +git clone https://git.movitzaaron.com/movitz/EMBS.git +cd EMBS +./embs.sh --check +``` + +You want to see `X server reachable: :0`. Then connect for real: + +```bash +./embs.sh +``` + +## Step 5 — Check it actually works + +Once you are logged in to the server, type: + +```bash +xeyes +``` + +**A pair of eyes should appear on your Mac.** If it does, the hard part is over. + +## Step 6 — One-off setup on the server + +Still on the server. Add the tools to your PATH and point at the department's licence server, so +you don't need a licence of your own: + +```bash +echo 'export LM_LICENSE_FILE=2100@cslm0.its.york.ac.uk' >> ~/.bashrc +echo 'export PATH=/opt/york/cs/net/xilinx_vivado-2025.1-x86_64-1/2025.1/Vivado/bin:$PATH' >> ~/.bashrc +``` + +Disconnect (`exit`) and reconnect (`./embs.sh`), then check the version: + +```bash +vivado -version +``` + +It must say **2025.1**. If it says 2020.x, the PATH hasn't taken effect — reconnect and try again. + +## Step 7 — Run Vivado + +```bash +vivado & +``` + +Vitis is launched from inside Vivado: **Tools → Launch Vitis IDE**. + +### What the flags do + +`embs.sh` is just a wrapper around: + +```bash +ssh -Y -C -o ServerAliveInterval=60 csteach0.york.ac.uk +``` + +| Flag | Meaning | +| --- | --- | +| `-Y` | Forward X11, so the GUI windows are drawn on your Mac. | +| `-C` | Compress the connection — X11 sends a lot of small messages. | +| `-o ServerAliveInterval=60` | Keepalive every 60s, so a long synthesis run isn't dropped. | + +It also exports `DISPLAY=:0` and starts XQuartz if needed, which is why it is safer than typing +the `ssh` command by hand. + +--- + +## Troubleshooting + +**It asks for my password every single time.** +Normal. The gateway uses two-factor authentication, so it always asks for a password (and maybe a +Duo approval) after using your key. Nothing is broken, and it can't be automated. + +**`xeyes` runs but no window appears, or it says "Can't open display".** +`DISPLAY` isn't set. `embs.sh` handles this for you; if you're connecting by hand, run +`export DISPLAY=:0` first, or start XQuartz (`open -a XQuartz`) and reconnect. + +**"REMOTE HOST IDENTIFICATION HAS CHANGED" / host key changed.** +Usually just means the relay server was rebuilt. Delete the offending line from +`~/.ssh/known_hosts` and reconnect. + +**My own `Host embs` alias hangs, then times out.** +It's missing its `ProxyCommand`. ssh only merges options from `Host` blocks whose pattern +matches, so a new alias does **not** inherit the `ProxyCommand` from the `csteach0` block. Copy +it into the new block, or just use `./embs.sh`. + +**Vivado feels slow.** +Expected — the GUI is being sent over the network. Start long synthesis runs and come back to them. +A hardware lab PC is far nicer when you can get one. + +## Good to know + +- Never put **spaces** in Vivado project names or paths — it genuinely breaks the tools. +- Watch your disk quota on the server (`quota -s`). Synthesis uses a lot; `~/.cache` is usually + safe to clear out. +- Your home directory on the server is your University filestore, so your projects persist between + sessions. +- **On Windows** the same server route works from WSL (follow the Linux instructions), but the X11 + part differs — you'd use an X server such as VcXsrv or Xming instead of XQuartz. + +## Where the original instructions live + +- Working Remotely — +- VLAB Quickstart — +- Using the VLAB — diff --git a/embs.sh b/embs.sh new file mode 100755 index 0000000..3e8298a --- /dev/null +++ b/embs.sh @@ -0,0 +1,99 @@ +#!/usr/bin/env bash +# +# embs.sh - connect to the York CS Linux server with the Vivado / Vitis GUI +# forwarded to the XQuartz X server running on this Mac. +# +# Vivado and Vitis have no macOS build, so they run on csteach0.york.ac.uk and +# their windows are drawn here by XQuartz over an X11-forwarded SSH connection. +# +# Usage: +# ./embs.sh interactive shell, X11 forwarded (normal use) +# ./embs.sh --check verify the local X server and show what would run +# ./embs.sh 'vivado -version' run one remote command, then disconnect +# +# The remote host can be overridden, e.g. EMBS_HOST=csteach1.york.ac.uk ./embs.sh +# +# Note: this script only prepares the local X server and starts ssh. The hop +# through the SSH gateway, and any 2FA prompt it raises, are handled by the +# ProxyCommand already configured in ~/.ssh/config. + +set -e + +HOST="${EMBS_HOST:-csteach0.york.ac.uk}" +XDPYINFO=/opt/X11/bin/xdpyinfo + +# Return the first local X display we can actually reach, or nothing. +working_display() { + local d + for d in "${DISPLAY:-}" ":0"; do + [ -n "$d" ] || continue + if [ -x "$XDPYINFO" ] && "$XDPYINFO" -display "$d" >/dev/null 2>&1; then + printf '%s' "$d" + return 0 + fi + done + return 1 +} + +start_xquartz() { + if [ ! -d /Applications/Utilities/XQuartz.app ]; then + echo "error: XQuartz is not installed." >&2 + echo " Install it with: brew install --cask xquartz" >&2 + return 1 + fi + echo "Starting XQuartz..." + open -a XQuartz || return 1 + local i + for i in $(seq 1 30); do + if "$XDPYINFO" -display :0 >/dev/null 2>&1; then + return 0 + fi + sleep 0.5 + done + return 1 +} + +CHECK_ONLY=no +if [ "${1:-}" = "--check" ]; then + CHECK_ONLY=yes + shift +fi + +# --- 1. Make sure there is a usable local X server --------------------------- +DISP="$(working_display || true)" +if [ -z "$DISP" ] && [ "$CHECK_ONLY" = no ]; then + if start_xquartz; then + DISP=":0" + fi +fi + +if [ -z "$DISP" ]; then + echo "warning: no X server reachable on this Mac." >&2 + echo " XQuartz is installed but may not be running, or DISPLAY is not exported." >&2 + echo " Try: open -a XQuartz (then log out and back in once)" >&2 + echo " Vivado / Vitis windows will NOT appear until this is fixed." >&2 +else + export DISPLAY="$DISP" +fi + +# --- 2. Report and connect --------------------------------------------------- +if [ "$CHECK_ONLY" = yes ]; then + echo "XQuartz installed : yes" + echo "X server reachable: ${DISP:-no}" + echo "DISPLAY would be : ${DISP:-}" + echo "Would run : ssh -Y -C -o ServerAliveInterval=60 $HOST" + if [ "$#" -gt 0 ]; then + echo "Remote command : $*" + fi + exit 0 +fi + +echo "Connecting to $HOST with DISPLAY=${DISPLAY:-} ..." +echo "If the gateway asks for a password or Duo approval, that is the university's 2FA." +echo + +if [ "$#" -gt 0 ]; then + exec ssh -Y -C -o ServerAliveInterval=60 "$HOST" "$@" +else + exec ssh -Y -C -o ServerAliveInterval=60 "$HOST" +fi diff --git a/remote-access-setup.md b/remote-access-setup.md new file mode 100644 index 0000000..b3c2d28 --- /dev/null +++ b/remote-access-setup.md @@ -0,0 +1,205 @@ +# EMBS — Remote access to the Xilinx tools (macOS) + +Source material: `working-remotely.md`, `vlab-quickstart-guide.md`, `using-the-vlab.md`, +plus the EMBS docs (Practical 1a, "Working Remotely", "Vivado Licencing and Installation"). + +## Why we cannot run the tools on this Mac + +Vivado / Vitis 2025.1 have **no macOS build at all** — AMD ship Linux (x86-64) and Windows only. +On top of that this is an Apple Silicon machine (arm64, macOS 27.0.1), so even a VM/emulation +route would be a fight. The tools therefore have to run on a **Linux machine at York**, and we +drive them over SSH with the GUI forwarded to this Mac with X11. + +## The three machines involved + +| Machine | Role | +| --- | --- | +| `ssh.york.ac.uk` | IT Services SSH gateway. The only York host reachable from off campus. | +| `csteach0.york.ac.uk` | CS teaching Linux server. **This is where Vivado/Vitis actually run.** Home dir = your university filestore. | +| `rts001.cs.york.ac.uk:2222` | VLAB relay — the rack of real Zybo Z7-10 boards. Only reachable *through* the gateway. | +| this Mac | X server (XQuartz) + terminal. Runs no Xilinx software. | + +Verified by probing from this Mac: + +* `ssh.york.ac.uk:22` — reachable. +* `rts001.cs.york.ac.uk:22` and `:2222` — **timed out** (firewalled, as documented). +* `csteach0.york.ac.uk:22` — **timed out** (must go via the gateway). +* `csteach0.york.ac.uk` resolves to `144.32.125.156`. + +So the gateway hop is mandatory, not optional. + +## What is already done on this Mac + +* `~/.ssh/config` already contains the York blocks for user `brs544` + (`ssh.york.ac.uk`, and `rts001.cs.york.ac.uk csteach0.york.ac.uk` with the ProxyCommand). +* An SSH key pair exists: `~/.ssh/id_ed25519` / `~/.ssh/id_ed25519.pub`. +* Python 3 (Homebrew) and OpenSSH 10.3 are available. + +## Current status + +* ✅ SSH key authorised — login to `csteach0.york.ac.uk` works. +* ✅ XQuartz installed. +* ⬜ **No VLAB keyfile** (`*.vlabkey`) anywhere under `$HOME`. This must come from Ian. +* ⬜ Xilinx PATH / licence lines on the server (one-off, step 4) — verify with `vivado -version`. + +### Two gotchas found by testing + +**1. The SSH gateway demands a second factor every time.** The gateway *accepts* the key +(`debug1: Server accepts key`) and then still asks for another method +(`gssapi-with-mic,password,keyboard-interactive`). That is the university's 2FA +(`AuthenticationMethods publickey,keyboard-interactive`), not a broken key. Expect a +password / Duo prompt on every connection through the gateway. `ssh -o BatchMode=yes` will +never work, so unattended or scripted logins are not possible. + +**2. `DISPLAY` is not exported on this Mac.** After installing XQuartz, `echo $DISPLAY` prints +nothing and `launchctl getenv DISPLAY` is empty — so a plain `ssh -Y` forwards nothing and the +windows silently never appear. Starting XQuartz *does* create a working server (verified: +`xdpyinfo -display :0` succeeds and `/tmp/.X11-unix/X0` exists). `embs.sh` below sets +`DISPLAY=:0` itself, which is exactly why it is safer than typing `ssh -Y` by hand. +(Logging out and back in also fixes it permanently.) + +## Step 1 — Authorise our key at York + +```bash +ssh-copy-id csteach0.york.ac.uk +``` + +This goes through the ProxyCommand to the gateway and then to `csteach0`. Expect to be asked for +your password **several times** (gateway, then `csteach0`). The gateway reads +`~/.ssh/authorized_keys` from your university Linux home directory, so copying the key to +`csteach0` also unlocks key-based auth on the gateway. + +Verify — this should print a hostname and your username with no password prompt: + +```bash +ssh -o BatchMode=yes csteach0.york.ac.uk 'echo OK $(hostname) as $(whoami)' +``` + +## Step 2 — Install XQuartz + +```bash +brew install --cask xquartz +``` + +(or download XQuartz 2.8.6 from — it supports macOS 10.13+ and is +arm64-native). **Log out and back in** after installing so `DISPLAY` is set up. + +## Step 3 — Connect (use `embs.sh`) + +```bash +cd ~/Projects/EMBS +./embs.sh +``` + +This is a thin wrapper around: + +```bash +ssh -Y -C -o ServerAliveInterval=60 csteach0.york.ac.uk +``` + +What it adds: it finds (or starts) XQuartz and exports `DISPLAY=:0` — necessary because +`DISPLAY` is unset on this Mac — then runs the ssh command above. Other modes: + +```bash +./embs.sh --check # verify the X server, connect to nothing +./embs.sh 'vivado -version' # run one remote command and exit +EMBS_HOST=csteach1.york.ac.uk ./embs.sh # override the host +``` + +Once connected, sanity-check X11 before committing to a 60 GB tool launch: + +```bash +xeyes # a pair of eyes should appear on the Mac +``` + +### What the flags mean + +| Flag | Meaning | +| --- | --- | +| `-Y` | Trusted X11 forwarding. Asks sshd to set the remote app's `DISPLAY` and proxy X11 traffic back down the SSH connection to the local X server. It does **not** talk to XQuartz itself — XQuartz is simply the endpoint the local `DISPLAY` points at. | +| `-X` | Untrusted forwarding: enables the X11 SECURITY extension, which restricts what the remote app may do and often breaks older Java/Tk toolkits. Vivado/Vitis misbehave under it, which is why the module docs use `-Y`. | +| `-C` | Compress the SSH connection. Worth it because X11 forwarding is chatty with small, repetitive drawing messages. Note the ProxyCommand's `-o Compression=no` applies only to the separate gateway hop. | +| `-o ServerAliveInterval=60` | Send a keepalive every 60 s of inactivity so an idle NAT/firewall does not silently drop a long synthesis run. | + +### Making the name memorable + +`embs.sh` gives you a short local command. If you would rather type just `ssh embs`, add this +block to `~/.ssh/config`: + +``` +Host embs + HostName csteach0.york.ac.uk + User brs544 + ProxyCommand ssh -A -T -o Compression=no ssh.york.ac.uk -W %h:%p + ForwardX11Trusted yes + Compression yes + ServerAliveInterval 60 +``` + +The `ProxyCommand` **must** be repeated here: ssh only merges options from blocks whose `Host` +pattern matches, and the existing `Host rts001.cs.york.ac.uk csteach0.york.ac.uk` block does not +match the name `embs`. Without it, `ssh embs` would try to reach `csteach0` directly and hang +until it timed out. (An alias alone also still leaves the `DISPLAY` problem above, which is why +`embs.sh` remains the more robust route.) + +## Step 4 — One-off setup on the server + +Per Practical 1a, add the tools to the PATH and point at the department's **floating licence +server** (so no personal AMD licence is needed while working on the CS servers): + +```bash +echo 'export LM_LICENSE_FILE=2100@cslm0.its.york.ac.uk' >> ~/.bashrc +echo 'export PATH=/opt/york/cs/net/xilinx_vivado-2025.1-x86_64-1/2025.1/Vivado/bin:$PATH' >> ~/.bashrc +``` + +Then reopen the terminal and check the version — it must be **2025.1**, not an older 2020.x that +may be earlier on the PATH: + +```bash +vivado -version +``` + +Vitis is normally launched from inside Vivado (`Tools -> Launch Vitis IDE`), so no separate +PATH entry is needed. + +## Step 5 — Get the VLAB keyfile (from Ian) + +Everything on the VLAB side is blocked until we have this. Once we do: + +```bash +scp ~/Downloads/.vlabkey csteach0.york.ac.uk:~/ +ssh csteach0.york.ac.uk 'chmod 0600 ~/*.vlabkey' +``` + +`vlab.py` **must run on the same machine as the tools** (i.e. on `csteach0`, not on the Mac) — +that is the whole point of the `localhost:12345` tunnel. Full VLAB usage is the next conversation. + +## Gotchas worth knowing up front + +* **Expect X11 to be slow.** Vivado's GUI over X11 from York is usable but sluggish; the new + VS Code-based Vitis IDE is heavier still. Prefer a hardware lab PC when you can, and do long + synthesis/implementation runs and come back. +* **`csteach0` is shared.** The VLAB default local port 12345 will collide with other students. + Pick your own with `-l`, e.g. `vlab.py -k key.vlabkey -l 20041 -u brs544`, and use the same + port in Vivado/Vitis. +* **Disk quota.** Synthesis eats space; a full `~/.cache` is the usual culprit. Check with + `quota -s`; aim for ~500 MB free. +* **No spaces** in Vivado project paths or workspace names — this genuinely breaks the tools. +* **Close the VLAB when done** (`Ctrl-a` then `k`, confirm `y`) — the exclusive board lock + expires 10 minutes after connecting anyway. +* **Host key warnings** about `rts001` usually just mean the relay was rebuilt; clear the stale + entry from `~/.ssh/known_hosts`. +* The VLAB gives you **UART only** — no buttons, no LEDs, no live HDMI. Plan designs so they can + be driven and observed over the serial line. (`--capture` can grab a JPEG of an AXI VDMA + framebuffer.) +* **The University VDS is not a route to the tools.** Its UniDesktop software list (MATLAB, R, + ArcGIS, VS Code, PuTTY, WinSCP, X2Go …) contains no Vivado/Vitis. It could only serve as a + Windows jump box to reach `csteach0`. + +## Immediate next actions + +1. `./embs.sh` and confirm `xeyes` appears. +2. If not already done, add the PATH / licence lines on the server (step 4) and run + `vivado -version` to confirm 2025.1. +3. Ask Ian for the VLAB keyfile. +4. Then the VLAB: `vlab.py` run **on csteach0**, board lock via `-l `. diff --git a/using-the-vlab.md b/using-the-vlab.md new file mode 100644 index 0000000..f66e411 --- /dev/null +++ b/using-the-vlab.md @@ -0,0 +1,137 @@ +SOURCE: https://iangray001.github.io/embs/docs/setup/vlab/ (2026-10-24 15:19) + +Using the VLAB + +Ask Ian if you need any help or encounter any problems with the VLAB or using the Xilinx tools remotely, or if you need a key to access the VLAB. + +Tip + +A more “step by step” version of this page exists, particularly for EMBS students, at The VLAB Quickstart Guide. + +The VLAB is complex infrastructure built specially for teaching here at the University. Please report any bugs or errors (or just annoying things) to us so that we can fix them. If you’re feeling motivated you can help us fix any issues on GitHub! + +The Virtual Lab is a rack of FPGA boards that are kept in the RTS Lab and are connected to the internet for your use. These boards are identical to the boards that you have in the hardware lab and the same bitfiles will work. The only difference is that you will not be able to use the buttons on the board, or observe the LEDs, so all interactions with your design will have to be via the UART (serial line). You should plan for this when building your systems. +Current Status of the VLAB +vlab_zybo-z7 +6 available 1 in use / 7 total +Updated 12 minutes ago +Key Facts + + The VLAB lets you use your existing designs, it doesn’t need anything changing in your hardware or software. + You will run the client script vlab.py to connect to a remote FPGA. + Once connected, you can connect the Xilinx tools (Vivado) to the remote FPGA through the VLAB, in order to program and debug the board. + The VLAB gives you access to the serial (UART) to let you interact with your design. + +Quick Start + +The VLAB client requires Python 3, so install this first. The client is tested on Linux and macOS, but should also work on Windows. + +Download the Virtual Lab client script from GitHub. + +You should have been given a Virtual Lab keyfile which allows you to access the VLAB. If not, speak to a demonstrator. To use the VLAB, run the script to connect and request a board. Note that you must run the VLAB script from the same place as you are running the Xilinx tools. If you are running Vivado remotely, run the script on that remote machine. + +For example, to request an EMBS board, use the following: + +./vlab.py -k + +This defaults to requesting a vlab_zybo-z7 board (the Digilent Zybo Z7-10 FPGAs used in EMBS). To request a different type of board use the -b flag. For example: + +./vlab.py -k -b vlab_zybo-z7 + +If the FPGA is available, you will be connected to the UART terminal on the board. Any keypresses will be sent to the FPGA, and any bytes it sends will appear in your terminal, the same as with a local screen connection. Whilst you are connected, the VLAB allows any of the Xilinx software tools to see the remote FPGA and program it (see below for instructions). + +When you connect to the VLAB, you will get an exclusive lock on your allocated board for ten minutes. After this time you won’t immediately be disconnected, but any other user wishing to connect to the same board type may cause your session to end. Your current lock expiry time is shown during connection and at the bottom of the VLAB shell window. + +See the README file for more information on client installation and usage. +Using Vitis with the VLAB + +You probably want to use the VLAB from Vitis most of the time. First connect to a VLAB board. Then in Vitis in your application component go to Settings -> launch.json and next to “Target Connection” click new. Give it a sensible name like vlab and set the following: + +Hostname: localhost +Port: 12345 + +“Test connection” should report that Vitis could communicate with the FPGA via the VLAB. If all is fine, click OK and ensure that Target Connection is now set to your new vlab connection. + +And thats it! From now on, all interactions with that application will now go over the VLAB, and so to work local again, go back in and set Target Connection back to Local [default]. +Using Vivado with the VLAB + +Using the VLAB from Vivado is very similar. In Vivado click “Open Hardware Manager” in the Flow Navigator in the left-hand column. Then click “Open Target” | “Open New Target” in the Flow Navigator. In the Open wizard click Next, select Remote Server, Next, and use the settings from above. Click Next and the tools should connect and see a Zybo Z7: + +Vivado Hardware Targets showing a detected Zybo Z7 FPGA via VLAB + +Click Next and Finish. You can send bitfiles to the FPGA by selecting Program Device from the Flow Navigator. +Exiting the VLAB + +Please close your VLAB connection when you are not using it so that other students can use the board (remember that your exclusive lock on a board will expire ten minutes after connecting anyway.). + +The VLAB terminal window is running screen. To close it, press and release Ctrl-a, then press ‘k’ and confirm with ‘y’. + +When using a Virtex FPGA board (or anything other than a Zynq), errors following the line “fpga configuration failed. DONE PIN is not HIGH” when disconnecting are normal, and can be ignored (we will tidy this up one day…). +Connecting through the SSH Gateway + +Due to the University’s firewall rules, the Virtual Lab relay server (rts001.cs.york.ac.uk) ) is only accessible from departmental machines, staff Linux compute servers, anything on the RTDS lab network, and all student lab PCs, or via the IT Services SSH service. Therefore, when off campus or using eduroam, the easiest way to access the VLAB (and other departmental servers) is through the IT Services SSH gateway. + +Once you have been granted access to the SSH gateway, the following SSH rules can be used to connect directly through to the VLAB by adding them to the ~/.ssh/config file on the computer you’re connecting from. + +Host ssh.york.ac.uk +User YOUR_ITSERVICES_USERNAME + +Host rts001.cs.york.ac.uk +User YOUR_VLAB_USERNAME +ProxyCommand ssh -A -T -o Compression=no ssh.york.ac.uk -W %h:%p + +The SSH gateway server also accepts key-based authentication, using the ~/.ssh/authorized_keys file from your standard university Linux home directory. +Graphical Output over the VLAB + +Viewing HDMI output is not natively supported by the VLAB — you cannot see the live video signal. However, the VLAB can reach into the FPGA over the Xilinx debugging interface, pull the current contents of the video frame buffer out of memory, and save it as a JPEG. This won’t give you smooth video, but it is a quick way to check what your design is actually drawing. +Quick capture with --capture (recommended) + +If your design drives HDMI through an AXI VDMA peripheral (as the standard HDMI example does), the client can grab a frame for you automatically. See Using the HDMI over the VLAB for more on how this works. + +First, connect to a board as normal and leave that session running. Then, in a second terminal, run the client again with --capture: + +./vlab.py -k --capture + +This locates the live frame buffer by reading the VDMA registers, captures and JPEG-compresses the frame on the board itself, and downloads it. By default the image is saved as capture_YYYYMMDD_HHMMSS.jpg; use -o to choose a filename: + +./vlab.py -k --capture -o myframe.jpg + +The capture runs on the FPGA’s second CPU core and does not disturb your running program, so you can take a snapshot at any point while your design executes. It is also much faster than the manual method described below, usually completing in a few seconds. + +Note + +--capture requires an up-to-date vlab.py. If you downloaded the client a while ago, the script will prompt you to update when you run it. + +The capture defaults to a VDMA peripheral base address of 0x43000000, which is correct for the EMBS HDMI example. If your block design places the VDMA somewhere else, pass its base address (from the Vivado Address Editor) with --vdma: + +./vlab.py -k --capture --vdma 0x43000000 + +Manual frame capture + +If your design does not use a VDMA (so --capture cannot find the frame automatically), you can still pull a frame out by hand if you know its memory address. + +Note that this script assumes that you are running on Linux because it uses ImageMagick and the Gnome Image Viewer. These can be installed on a Debian-based Linux with the following: + +sudo apt-get install eog imagemagick + +You can avoid installing Eye of Gnome by switching the image viewer the script uses. On the exec eog $filename.png line, switch eog to (for example)gwenview for KDE or open for macOS. + +The first task is to get the memory address of the video frame you want to view. In the HDMI example code which you are probably working with, two frame buffers are set up with the following code. + +u32 frameBuf[DISPLAY_NUM_FRAMES][MAX_FRAME] __attribute__((aligned(0x20))); // Frame buffers for video data +void *pFrames[DISPLAY_NUM_FRAMES]; // Array of pointers to the frame buffers + +This is called multiple buffering and allows the video hardware to be drawing one frame to the screen, whilst the CPU is preparing the next frame. You can get the memory address of a frame by simply printing it out to the console. + +printf("Address of frame: %p\n", pFrames[0]); + +In the HDMI example this will be 0x11ce80 but this is likely to change frequently as you edit your code. Once you have the address of the frame you are interested in, download this script: + +In Vivado’s menus, select Tools | Run Tcl Console (or in Vitis, Xilinx | XSCT Console) to view the debugging interface. The XSCT console has the prompt xsct%. Set the target address of frame and then run the script. + +xsct% set base 0x11ce80 +xsct% source /path/to/readimage.tcl + +This will fetch the frame, convert it to a PNG, and show it in an image viewer. By default the script only grabs every 20th line, but to make it grab the entire frame set the following: + +xsct% set stride 1 diff --git a/vlab-quickstart-guide.md b/vlab-quickstart-guide.md new file mode 100644 index 0000000..c5e20fd --- /dev/null +++ b/vlab-quickstart-guide.md @@ -0,0 +1,90 @@ +SOURCE: https://iangray001.github.io/embs/docs/setup/vlab-quickstart/ (2026-10-24 15:18) + +VLAB Quickstart Guide + +Tip + +The VLAB is a remote testing environment. It will let you test designs that you have already constructed, but you will need a way to access the development tools. You can install them yourself, or use a remote desktop environment. Please see this page for details. +Current Status of the VLAB +vlab_zybo-z7 +6 available 1 in use / 7 total +Updated 12 minutes ago +Intro + +To use the VLAB you need a Virtual Lab keyfile. If you don’t have one and think that you should, speak to Ian. + +Download the VLAB script and run it. You must run the VLAB software from the location where you are running the Xilinx tools. i.e. if you have installed them on your computer, run them on your computer. If you are running on the VDS, download and run the tools there. + +cd Downloads +python vlab.py --user yourusername --key yourkeyfile.vlabkey + +yourusername is your IT services username (i.e. abc500). + +On Linux: + +wget https://raw.githubusercontent.com/RTSYork/VLAB/master/vlab.py +chmod +x vlab.py +./vlab.py --user yourusername --key yourkeyfile.vlabkey + +The script requires Python 3 so install it if you need to. The script defaults to requesting a vlab_zybo-z7 board (the Zybo Z7-10 boards used in EMBS). It should run, request an FPGA board, connect to a free one, reset it ready for use, and eventually show you a connected terminal. Please close the terminal when you are done, see the section below on how to exit. + +If you are running the tools on your home machine, you need to set up some SSH configuration so that your computer can see the VLAB servers. Ensure that you have performed the steps in the Connecting through the SSH Gateway section. +Exiting the VLAB + +Please close your VLAB connection when you are not using it so that other students can use the board. The VLAB terminal window is running screen. To close it, press and release Ctrl-a, then press k and confirm with y. +Using Vitis with the VLAB + +You probably want to use the VLAB from Vitis most of the time. First connect to a VLAB board. Then in Vitis in your application component go to Settings -> launch.json and next to “Target Connection” click new. Give it a sensible name like vlab and set the following: + +Hostname: localhost +Port: 12345 + +“Test connection” should report that Vitis could communicate with the FPGA via the VLAB. If all is fine, click OK and ensure that Target Connection is now set to your new vlab connection. + +And thats it! From now on, all interactions with that application will now go over the VLAB, and so to work local again, go back in and set Target Connection back to Local [default]. +Using Vivado with the VLAB + +Using the VLAB from Vivado is very similar. In Vivado click “Open Hardware Manager” in the Flow Navigator in the left-hand column. Then click “Open Target” | “Open New Target” in the Flow Navigator. In the Open wizard click Next, select Remote Server, Next, and use the settings from above. Click Next and the tools should connect and see a Zybo Z7: + +Vivado Hardware Targets showing a detected Zybo Z7 FPGA via VLAB + +Click Next and Finish. You can send bitfiles to the FPGA by selecting Program Device from the Flow Navigator. +Troubleshooting +The permissions on the key are too permissive + +The SSH client requires that your private key is only visible to you and not to other users on the system. Depending on how you downloaded the key you might find that your permissions are too permissive. On Linux this is easily fixed by entering: + +chmod 0600 mykey.vlabkey + +On Windows: + + Right click your keyfile and select Properties. + + Go to the Security tab, click Advanced. + + Click Disable Inheritance and “Remove all inherited permissions from this object”. + + Click Add and “Select a principal”. + + Enter your username, which if you are on a lab machine will be IT services username (abc500) and click OK. + + If it is your home machine it is whatever username you set up. + + Click Full Control and OK. + + It should look something like this: + +Windows Advanced Security Settings showing correct keyfile permissions + + Click OK, OK, and SSH should now be happy. + +Host Keys have Changed + +If you get a message about host keys changing (and you’re sure that nobody is actually trying to man-in-the-middle attack your connection), it’s likely that we’ve just updated the VLAB relay server since you last connected. Follow the instructions in the error message to clear the key from your known_hosts file. If you’re unsure about anything you can always email us for help. +Port is in use / Using the VLAB on a Shared Machine + +If you’re connecting to the VLAB on a shared machine where multiple people might be connecting at once (e.g. from one of the department’s compute servers) you will need to specify a custom local port so that your connection doesn’t collide with another user’s. You can use the -l or --localport option to vlab.py to specify a port that is different to the default value (12345), then specify this in Vivado instead. Almost any port in the range 1024 to 65535 should work if it is free. For example: + +python vlab.py -k mykey.vlabkey -l 20000 -u itsusername + +Where itsusername is your ITS username, i.e. abc500. diff --git a/vlab.py b/vlab.py new file mode 100644 index 0000000..6ebd654 --- /dev/null +++ b/vlab.py @@ -0,0 +1,477 @@ +#!/usr/bin/env python3 + +""" +The VLAB client script. + +Example usage: + ./vlab.py -k keyfile.vlabkey -b an_fpga_board + +The script will assume your username is the same as the system user. To specify a different username +use the -u option. + +The VLAB server and port are given as defaults to the -r and -p arguments so the user should not +have to specify them, but they can be overridden if required. + +Ian Gray, 2017-2026 +""" + +import argparse +import os +import shlex +import signal +import socket +import sys +import time +import urllib.error +import urllib.request +from subprocess import DEVNULL, PIPE, Popen +from typing import NoReturn + +############################ +# Update version string here and in 'current_version' file when updating this script +# Version number must be in 'x.y.z' format +current_version = "1.3.0" +current_branch = "master" +############################ + + +def err(error_string) -> NoReturn: + print(error_string) + sys.exit(1) + + +parser = argparse.ArgumentParser(description="VLAB client script") +parser.add_argument( + "-r", + "--relay", + nargs=1, + default=["rts001.cs.york.ac.uk"], + help="The hostname of the relay server.", +) +parser.add_argument( + "-p", + "--port", + nargs=1, + default=["2222"], + help="The ssh port of the relay server to connect to.", +) +parser.add_argument( + "-l", + "--localport", + nargs=1, + default=["12345"], + help="Local port to forward connections to.", +) +parser.add_argument( + "-k", "--key", nargs=1, help="VLAB keyfile to use for authentication." +) +parser.add_argument("-u", "--user", nargs=1, help="VLAB username.") +parser.add_argument( + "-b", "--board", nargs=1, default=["vlab_zybo-z7"], help="Requested board class." +) +parser.add_argument("-s", "--serial", nargs=1, help="Requested board serial number.") +parser.add_argument( + "-v", + "--verbose", + default=False, + action="store_true", + help="Enable verbose logging.", +) +parser.add_argument( + "-c", + "--capture", + default=False, + action="store_true", + help="Capture the FPGA framebuffer and save as JPEG.", +) +parser.add_argument( + "-o", + "--output", + nargs=1, + help="Output filename for capture (default: capture_YYYYMMDD_HHMMSS.jpg)", +) +parser.add_argument( + "--vdma", + nargs=1, + help="Base address of the framebuffer VDMA peripheral for --capture, e.g. 0x43000000 " + "(default: 0x43000000).", +) +parser.add_argument( + "-n", + "--no-terminal", + default=False, + action="store_true", + help="Hold the board and the port forward open without starting a terminal. " + "Leaves the board's serial port free for --capture-serial. For scripting.", +) +parser.add_argument( + "--capture-serial", + nargs=1, + metavar="SECONDS", + help="Capture the board's serial output for the given number of seconds and write " + "it to stdout, or to --output if given. Needs a session started with " + "--no-terminal.", +) +parsed = parser.parse_args() + +error_info = ( + "Read the instructions at\n" + "\thttps://iangray001.github.io/embs/docs/setup/vlab-quickstart/" +) + + +# Check for an update from GitHub repository +update_url = "https://raw.githubusercontent.com/RTSYork/VLAB/{}/client_version".format( + current_branch +) + +if parsed.verbose: + print("Checking for update at URL: {}".format(update_url)) + +req = urllib.request.Request(update_url) +try: + response = urllib.request.urlopen(req) + content = response.readline() + remote_version_string = content.decode("utf-8") + remote_version = tuple(map(int, (remote_version_string.split(".")))) + local_version = tuple(map(int, (current_version.split(".")))) + if local_version < remote_version: + print("A new version of the VLAB script is available on GitHub") + print( + "You have version v{} and the latest is v{}".format( + current_version, remote_version_string + ) + ) + print( + "Download the latest version from https://raw.githubusercontent.com/RTSYork/VLAB/{}/vlab.py".format( + current_branch + ) + ) + print() + try: + input("Press Control-C to exit, or press Enter to continue...") + except KeyboardInterrupt: + sys.exit(0) +except urllib.error.URLError as e: + print("Error checking for script updates:", e.reason) + +# Check the keyfile exists +if not parsed.key: + err("Specify a keyfile with --key.") +if not os.path.isfile(parsed.key[0]): + err( + "Keyfile {} does not exist. Specify a keyfile with --key.".format(parsed.key[0]) + ) + +# Handle capture mode +if parsed.capture: + ssh_cmd = [ + "ssh", + "-oPasswordAuthentication=no", + "-i", + parsed.key[0], + "-p", + parsed.port[0], + ] + if parsed.user is not None: + ssh_cmd.extend(["-l", parsed.user[0]]) + # Encode an optional VDMA base address into the relay command token (capture[:vdma]), + # mirroring the boardclass:port:serial form used for board sessions. The relay validates + # the value before use; omitting it lets the boardserver fall back to its built-in default. + if parsed.vdma is not None: + ssh_cmd.extend([parsed.relay[0], "capture:{}".format(parsed.vdma[0])]) + else: + ssh_cmd.extend([parsed.relay[0], "capture"]) + + if parsed.verbose: + print("Capture ssh command: {}".format(ssh_cmd)) + + print("Requesting framebuffer capture...") + proc = Popen(ssh_cmd, stdout=PIPE) + stdout, _ = proc.communicate() + + if proc.returncode != 0 or len(stdout) == 0: + if len(stdout) > 0: + print(stdout.decode("utf-8", errors="replace").strip()) + else: + print("Capture failed.") + sys.exit(1) + + # Verify JPEG magic bytes + if len(stdout) < 2 or stdout[:2] != b"\xff\xd8": + print(stdout.decode("utf-8", errors="replace").strip()) + sys.exit(1) + + if parsed.output: + filename = parsed.output[0] + else: + filename = "capture_{}.jpg".format(time.strftime("%Y%m%d_%H%M%S")) + + with open(filename, "wb") as f: + f.write(stdout) + print("Saved to {} ({} bytes)".format(filename, len(stdout))) + sys.exit(0) + +# Handle serial capture mode. Like --capture this is a one-shot command against a +# session the user already holds, so it needs no port forward of its own. +if parsed.capture_serial: + seconds = parsed.capture_serial[0] + if not seconds.isdigit() or int(seconds) < 1: + err("--capture-serial takes a whole number of seconds.") + + ssh_cmd = [ + "ssh", + "-oPasswordAuthentication=no", + "-i", + parsed.key[0], + "-p", + parsed.port[0], + ] + if parsed.user is not None: + ssh_cmd.extend(["-l", parsed.user[0]]) + ssh_cmd.extend([parsed.relay[0], "serial:{}".format(seconds)]) + + if parsed.verbose: + print("Serial capture ssh command: {}".format(ssh_cmd), file=sys.stderr) + + # Only the captured bytes go to stdout, so that the caller can redirect them. + # The relay writes its own progress and errors to stderr, which passes through. + proc = Popen(ssh_cmd, stdout=PIPE) + captured, _ = proc.communicate() + + if proc.returncode != 0: + sys.exit(proc.returncode) + + if parsed.output: + with open(parsed.output[0], "wb") as f: + f.write(captured) + print( + "Saved {} bytes to {}".format(len(captured), parsed.output[0]), + file=sys.stderr, + ) + else: + sys.stdout.buffer.write(captured) + sys.stdout.buffer.flush() + sys.exit(0) + +# Check that the requested ports are free to use +local_port = int(parsed.localport[0]) +with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s: + local_port_in_use = s.connect_ex(("localhost", local_port)) == 0 + +if local_port_in_use: + err( + "Error: Local port {} is in use by another user on this machine, or otherwise unavailable. " + "Specify a different port with --localport or -l.\n" + "\nEach user must choose their own unique local port when running on a shared machine (e.g. a departmental " + "server).\nSee the section on 'Using the VLAB on a Shared Machine' at " + "https://wiki.york.ac.uk/display/RTS/The+VLAB+Quickstart+Guide for more information.".format( + local_port + ) + ) + +# First get a port to use on the relay server +if parsed.user is not None: + ssh_cmd = [ + "ssh", + "-oPasswordAuthentication=no", + "-i", + parsed.key[0], + "-p", + parsed.port[0], + "-l", + parsed.user[0], + parsed.relay[0], + "getport", + ] +else: + ssh_cmd = [ + "ssh", + "-oPasswordAuthentication=no", + "-i", + parsed.key[0], + "-p", + parsed.port[0], + parsed.relay[0], + "getport", + ] +if parsed.verbose: + print("First ssh command: {}".format(ssh_cmd)) +stdout, stderr = Popen(ssh_cmd, stdout=PIPE, stderr=PIPE).communicate() + +try: + error = stderr.decode("ascii").strip() +except UnicodeError: + error = "" + reply = None + err("Could not decode error output from ssh subprocess") + +if len(stdout) == 0 and len(error) > 0: + errstr = "" + if error.find("UNPROTECTED PRIVATE KEY FILE") != -1: + errstr += "The permissions on the key {} are too permissive.\n".format( + parsed.key[0] + ) + errstr += "Only your user should be able to access the key, or it will be rejected by ssh.\n" + errstr += "To fix this, on Linux run the command\n\tchmod 0600 {}\n".format( + parsed.key[0] + ) + errstr += "On Windows, see the instructions at the link below.\n" + elif ( + error.find("Operation timed out") != -1 + or error.find("Connection refused") != -1 + ): + errstr += "Cannot see the VLAB relay server: {}\n".format(parsed.relay[0]) + errstr += "Try the following:\n\tssh {}\n".format(parsed.relay[0]) + errstr += "You should get a password prompt:\n\t> @{}'s password\n".format( + parsed.relay[0] + ) + errstr += "If this doesn't connect, or the prompt is for any other server, set up your .ssh/config file\n" + elif error.find("Permission denied") != -1: + errstr += error + errstr += "\nEnsure that you have copied your private key:\n" + errstr += "\tssh-copy-id csteach1.york.ac.uk\n\t(or csresearch1.york.ac.uk for staff)\n" + errstr += "Also, if your VLAB username is different to your normal username, set it with -u:\n" + errstr += "\t./vlab.py -k {} -u myusername\n".format(parsed.key[0]) + elif error.find("Resource temporarily unavailable") != -1: + errstr += error + errstr += ( + "\nThis often means a firewall has blocked the connection. Try temporarily disabling your firewall " + "application.\n" + ) + elif error.find("Connection closed by") != -1: + errstr += error + errstr += ( + "\nEnsure that you have set the correct usernames in your ssh config.\n" + ) + elif error.find("REMOTE HOST IDENTIFICATION HAS CHANGED") != -1: + errstr += error + errstr += ( + "\n\n\nThe host key in the VLAB has changed. This should not happen and might indicate a " + "man-in-the-middle attack.\n" + ) + errstr += "If you are sure this is not the case, delete the line mentioned above from the file ~/.ssh/known_hosts\n" + else: + print(error) + errstr += error_info + err(errstr) + +try: + reply = stdout.decode("ascii").strip() +except UnicodeError: + reply = None + err( + "Invalid reply from VLAB server. Incorrect message format.\n{}".format( + error_info + ) + ) + +if len(reply) > 9: + if reply[:9] == "VLABPORT:": + port_string = reply[9:] + ephemeral_port = int(port_string) + else: + ephemeral_port = None + err("Invalid reply from VLAB server. Wrong header.\n{}".format(error_info)) +else: + ephemeral_port = None + err("Invalid reply from VLAB server. Message too short.\n{}".format(error_info)) + +print( + "Tunnelling to relay server '{}' using port {}...".format( + parsed.relay[0], ephemeral_port + ) +) + +# Now create the actual connection +ssh_user = "" +if parsed.user is not None: + ssh_user = " -l {} ".format(parsed.user[0]) + +# Assemble the command we send to the relay shell +if parsed.serial is not None: + relay_command = "{}:{}:{}".format(parsed.board[0], ephemeral_port, parsed.serial[0]) +else: + relay_command = "{}:{}".format(parsed.board[0], ephemeral_port) + +# Ask the relay to allocate and tunnel as usual but not to start a terminal, so +# that the board's serial port stays free for --capture-serial. +if parsed.no_terminal: + relay_command = "noterm:{}".format(relay_command) + + +ssh_cmd = ( + "ssh -L {}:localhost:{} -o PasswordAuthentication=no -o ExitOnForwardFailure=yes " + "-e none -i {} {} -p {} -tt {} {}".format( + local_port, + ephemeral_port, + parsed.key[0], + ssh_user, + parsed.port[0], + parsed.relay[0], + relay_command, + ) +) + +if parsed.verbose: + print("Second ssh command: {}".format(ssh_cmd)) + +if not parsed.no_terminal: + os.system(ssh_cmd) + sys.exit(0) + +# Not shell=True: the board is released when ssh disconnects, so this process must +# be able to signal ssh itself rather than an intervening /bin/sh. +proc = Popen( + shlex.split(ssh_cmd), stdin=DEVNULL, stdout=PIPE, bufsize=1, universal_newlines=True +) + +if proc.stdout is None: + err("Failed to capture stdout from SSH subprocess.") + + +def end_session(signum=None, frame=None): + _ = (signum, frame) # discard the parameters to avoid unused error + if proc.poll() is None: + proc.terminate() + + +# A script will stop this with SIGTERM, and a closing terminal sends SIGHUP. +# Either way the board must be handed back rather than left locked. +for _sig in (signal.SIGTERM, signal.SIGHUP): + signal.signal(_sig, end_session) + +ready = False +try: + for line in proc.stdout: + line = line.rstrip() + if not ready and line.endswith("VLAB_SESSION_READY"): + ready = True + print("VLAB_READY:{}".format(local_port), flush=True) + print( + "Board ready. hw_server is forwarded to localhost:{}.".format( + local_port + ), + flush=True, + ) + print( + "Leave this running while you use the board; the lock is released when it exits.", + flush=True, + ) + continue + if line: + print(line, flush=True) +except KeyboardInterrupt: + pass +finally: + end_session() + try: + proc.wait(timeout=30) + except Exception: + proc.kill() + proc.wait() + +if not ready: + err("The board session never became ready.") + +sys.exit(proc.returncode) diff --git a/working-remotely.md b/working-remotely.md new file mode 100644 index 0000000..0bdafc0 --- /dev/null +++ b/working-remotely.md @@ -0,0 +1,79 @@ +SOURCE: https://iangray001.github.io/embs/docs/setup/ (2026-10-24 15:18) + +Working Remotely + +This page describes how to use the Xilinx FPGA development tools from your own computer, and how to configure VLAB connections when working off campus. Contents +Local Xilinx Tools Installation +Installation Notes for EMBS Students + +At the time of writing, the version of the tools installed in the student hardware labs is 2025.1. Xilinx only directly support some specific distributions of Linux so you might get an error about missing libraries which can be fixed by following this link. + +Note + +The lab material also works fine with version 2025.2, but projects created in .2 will not be usable in .1. + +Installing the Xilinx software on your computer may seem the simplest solution, but they are large; around 60GB for the bare minimum set of features required for EMBS, and increasing to about triple that for a full install (which is rarely necessary and not recommended). + +With that said, if you want to go down this route you can. First go to the Xilinx website, create a free account, download the appropriate installer and run it. + +On Linux the file will be called something like FPGAs_AdaptiveSoCs_Unified_SDI_2025.1_0530_0145_Lin64.bin. You need to make it executable then run it: + +chmod +x FPGAs_AdaptiveSoCs_Unified_SDI_2025.1_0530_0145_Lin64.bin +./FPGAs_AdaptiveSoCs_Unified_SDI_2025.1_0530_0145_Lin64.bin + +For EMBS, you need to install Vitis, Vivado, (Vitis HLS if this is a separate option), and to Install Cable Drivers. Under “Devices” turn on support for all the types of FPGAs that you will be using. For the Zybo in EMBS just turn on “SoCs”. Depending on the exact version you are installing it will look something like this: + +Vitis installer showing recommended component and device selections + +After a long download and installation process, the tools should now be installed. They can be run from the launchers created by the installation, or from a terminal as follows: + +/tools/Xilinx/Vivado//Vivado/bin/vivado + +Licensing + +The Zybo Z7-10 board uses a Zynq-7000 XC7Z010 device, which is supported by the free Vivado ML Standard Edition. You do not need to purchase a licence or obtain a voucher code. However you will need to go get a licence file from AMD/Xilinx. Instructions for doing this are detailed here. +Using the Zybo Z7 (EMBS) boards + +If you are using a Zybo board (e.g. for EMBS) you will also need to install the Digilent board definition files. To do this, in the New Project wizard you will get to the “Default Part” page. Select Boards, and Refresh, to download the catalogue of boards from Xilinx. Find the Zybo Z7-10 board and click the install button (the downwards arrow in the Status column). + +Vivado New Project board selection with Zybo Z7-10 highlighted + +Alternatively you can download the archive of the vivado-boards Github repository and extract it. After installing Vivado, open the extracted archive and copy the ‘new/board_files/zybo-z7-10’ folder into: + +/tools/Xilinx/Vivado//data/boards/board_files + +(Assuming you installed the tools to /tools/Xilinx. This same process works for the Windows version, but to wherever Windows installs the tools instead.) +Connecting through the SSH Gateway + +If you are trying to access the VLAB from your home machine, you need to set up SSH access through the IT Services SSH gateway. Do the following: +Linux / macOS + +Create an SSH key pair on your local machine with ssh-keygen. + +ssh-keygen + +It will ask where to save the keys, accept the defaults. Add the following to your SSH config file (~/.ssh/config). If you don’t already have such a file, create it. +~/.ssh/config + +Host ssh.york.ac.uk +User YOUR_USERNAME + +Host rts001.cs.york.ac.uk csteach0.york.ac.uk +User YOUR_USERNAME +ProxyCommand ssh -A -T -o Compression=no ssh.york.ac.uk -W %h:%p + +Once this is done you can type: + +ssh-copy-id csteach0.york.ac.uk + +to copy your key to the SSH Gateway. (If you are research staff, use csresearch1.york.ac.uk). You will have to enter your password multiple times. You should now be able to just connect using SSH: + +ssh -Y csteach0.york.ac.uk + +You can use this to run the Xilinx applications on the CS servers. On Linux this will just work, but on other operating systems you will need to install an X server to be able to see the GUI of the tools (such as XQuartz for macOS, or Xming for Windows). Install and run the X server and now if you run things they will magically appear on your own desktop as if you were running them locally (albeit slowly). +Windows 11 + +We recommend using the Ubuntu distribution for the Windows Subsystem for Linux although other Linux distros should work fine as well. Once installed, run the Ubuntu “app” and then follow the Linux instructions above. +Running the VLAB + +Now that you have the tools running remotely, you will need to use the VLAB to connect to an FPGA and work with it. The VLAB Quickstart Guide is here.