recover_underflow -> break_realtime

artiq/coredevice/core.py

@@ -129,6 +129,6 @@ class Core(AutoDB):
         return cycles_to_time(syscall("rtio_get_counter"))
 
     @kernel
-    def recover_underflow(self):
+    def break_realtime(self):
         t = syscall("rtio_get_counter") + 125000
         at(cycles_to_time(t))

benchmarks/pulse_rate.py

@@ -20,7 +20,7 @@ class PulseRate(Experiment, AutoDB):
                     delay(cycles_to_time(T))
             except RTIOUnderflow:
                 T += 1
-                self.core.recover_underflow()
+                self.core.break_realtime()
             else:
                 self.pulse_rate = cycles_to_time(2*T)
                 break

doc/manual/faq.rst

@@ -4,6 +4,11 @@ FAQ
 How do I ...
 ============
 
+prevent my first RTIO command from causing an underflow?
+--------------------------------------------------------
+
+The RTIO timestamp counter starts counting at zero at the beginning of the first kernel run on the core device. The first RTIO event is programmed with a small timestamp above zero. If the kernel needs more time than this timestamp to produce the event, an underflow will occur. You can prevent it by calling ``break_realtime`` just before programming the first event.
+
 override the `sysclk` frequency of just one DDS?
 ------------------------------------------------
 
@@ -12,7 +17,7 @@ Override the parameter using an argument in the DDB.
 organize parameters in folders?
 -------------------------------
 
-Use gui auto-completion and filtering.
+Use GUI auto-completion and filtering.
 Names need to be unique.
 
 enforce functional dependencies between parameters?

doc/manual/getting_started.rst

@@ -47,7 +47,7 @@ Modify the code as follows: ::
         @kernel
         def run(self):
             s = input_led_state()
-            self.core.recover_underflow()
+            self.core.break_realtime()
             if s:
                 self.led.on()
             else:
@@ -63,7 +63,7 @@ You can then turn the LED off and on by entering 0 or 1 at the prompt that appea
 
 What happens is the ARTIQ compiler notices that the ``input_led_state`` function does not have a ``@kernel`` decorator and thus must be executed on the host. When the core device calls it, it sends a request to the host to execute it. The host displays the prompt, collects user input, and sends the result back to the core device, which sets the LED state accordingly.
 
-The ``recover_underflow`` call is necessary to waive the real-time requirements of the LED state change (as the ``input_led_state`` function can take an arbitrarily long time). This will become clearer later as we explain timing control.
+The ``break_realtime`` call is necessary to waive the real-time requirements of the LED state change (as the ``input_led_state`` function can take an arbitrarily long time). This will become clearer later as we explain timing control.
 
 Algorithmic features
 --------------------