# 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 <https://www.xquartz.org/> — 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/<yourkey>.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 <your own port>`.