206 lines
9.0 KiB
Markdown
206 lines
9.0 KiB
Markdown
# 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>`.
|