From f7e10759dca56c09eae2723dd5baebc02542ce40 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Robert=20J=C3=B6rdens?= <rj@quartiq.de>
Date: Mon, 8 Jul 2019 18:30:19 +0200
Subject: [PATCH] suservo: note requirement to stop servo when accessing state

As already mentioned in the gateware.

One alternative would be to detect address collisions and
stall the read for one cycle.

Note that there will in general not be a consistent view of the servo
state unless the servo is stopped.

close #1337
---
 artiq/coredevice/suservo.py | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/artiq/coredevice/suservo.py b/artiq/coredevice/suservo.py
index 7f30112ce..48cc013fc 100644
--- a/artiq/coredevice/suservo.py
+++ b/artiq/coredevice/suservo.py
@@ -195,6 +195,10 @@ class SUServo:
 
         This method does not advance the timeline but consumes all slack.
 
+        If reading servo state through this method collides with the servo
+        writing that same data, the data can become invalid. To ensure
+        consistent and valid data, stop the servo before using this method.
+
         :param adc: ADC channel number (0-7)
         :return: 17 bit signed X0
         """
@@ -225,6 +229,10 @@ class SUServo:
 
         This method does not advance the timeline but consumes all slack.
 
+        If reading servo state through this method collides with the servo
+        writing that same data, the data can become invalid. To ensure
+        consistent and valid data, stop the servo before using this method.
+
         The PGIA gain setting must be known prior to using this method, either
         by setting the gain (:meth:`set_pgia_mu`) or by supplying it
         (:attr:`gains` or via the constructor/device database).
@@ -454,6 +462,10 @@ class Channel:
 
         This method does not advance the timeline but consumes all slack.
 
+        If reading servo state through this method collides with the servo
+        writing that same data, the data can become invalid. To ensure
+        consistent and valid data, stop the servo before using this method.
+
         :param profile: Profile number (0-31)
         :return: 17 bit unsigned Y0
         """
@@ -468,6 +480,10 @@ class Channel:
 
         This method does not advance the timeline but consumes all slack.
 
+        If reading servo state through this method collides with the servo
+        writing that same data, the data can become invalid. To ensure
+        consistent and valid data, stop the servo before using this method.
+
         :param profile: Profile number (0-31)
         :return: IIR filter output in Y0 units of full scale
         """