From 873aa1cff5a6140fa2ad488d0362ccd6bb61a832 Mon Sep 17 00:00:00 2001
From: occheung <dc@m-labs.hk>
Date: Tue, 13 Jan 2026 10:34:57 +0800
Subject: [PATCH] suservo: update JSON

- There are more attributes to the SU-Servo entry. Omitted because most of them are rarely used.
- The legacy JSON config are kept such that there are instructions for release-8 (soon-to-be legacy) branch, and;
- The urukul EEM entries are substantially revamped.
---
 src/hw/suservo.md | 28 +++++++++++++++++++++++++---
 1 file changed, 25 insertions(+), 3 deletions(-)

diff --git a/src/hw/suservo.md b/src/hw/suservo.md
index a1af88e..1eed705 100644
--- a/src/hw/suservo.md
+++ b/src/hw/suservo.md
@@ -4,6 +4,31 @@
 
 ## JSON
 
+With enabled SUServo mode, you only need to add `suservo` to JSON file, with its Sampler and Urukul(s) removed.
+
+### ARTIQ 9+ Entry
+
+```json
+{
+   "type": "suservo",
+   "sampler_ports": [<port num>, <port num>],
+   "urukul_ports": [[<port num>, <port num>], ..], // A list of port pairs
+   "clk_sel": 2,
+   "synchronization": true/false,
+   "proto_rev": <8 or 9, default 9> // CPLD firmware version
+}
+```
+
+### Legacy Entry
+
+__This is only applicable prior to ARTIQ-9. Please use the up-to-date entries otherwise.__
+
+Here are the key differences from the up-to-date entries:
+- Urukul EEM ports must be specified via `urukul0_ports` and `urukul1_ports`, which implies;
+- At most 2 Urukuls per SU-Servo.
+- Urukul synchronization is not supported.
+- Protocal revision (`proto_rev`) is unconfigurable.
+
 ```json
 {
   "type": "suservo",
@@ -11,12 +36,9 @@
   "urukul0_ports": [<port num>, <port num>],
   "urukul1_ports": [<port num>, <port num>], // optional
   "clk_sel": 2, // select 0 to 2
-  "proto_rev": <8 or 9, default 9> // CPLD firmware version
 }
 ```
 
-With enabled SUServo mode, you only need to add `suservo` to JSON file, with its Sampler and Urukul(s) removed.
-
 ## Building and Flashing
 
 A SU-Servo consists of a set of Samplers and Urukuls.