Add EMBS remote access setup: embs.sh, README guide, VLAB docs

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 <https://www.xquartz.org/> 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 — <https://iangray001.github.io/embs/docs/setup/>
+- VLAB Quickstart — <https://iangray001.github.io/embs/docs/setup/vlab-quickstart/>
+- Using the VLAB — <https://iangray001.github.io/embs/docs/setup/vlab/>