From 2adf9d91df81ef04d8c89ce40f024c1a164e47c0 Mon Sep 17 00:00:00 2001
From: Sebastien Bourdeauducq <sb@m-labs.hk>
Date: Sun, 3 May 2015 20:42:42 +0800
Subject: [PATCH] recover_underflow -> break_realtime

---
 artiq/coredevice/core.py       | 2 +-
 benchmarks/pulse_rate.py       | 2 +-
 doc/manual/faq.rst             | 7 ++++++-
 doc/manual/getting_started.rst | 4 ++--
 4 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/artiq/coredevice/core.py b/artiq/coredevice/core.py
index 043601f47..2467980f5 100644
--- a/artiq/coredevice/core.py
+++ b/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))
diff --git a/benchmarks/pulse_rate.py b/benchmarks/pulse_rate.py
index 912cbe592..4de78fa06 100644
--- a/benchmarks/pulse_rate.py
+++ b/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
diff --git a/doc/manual/faq.rst b/doc/manual/faq.rst
index 0e598d6de..de9e59006 100644
--- a/doc/manual/faq.rst
+++ b/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?
diff --git a/doc/manual/getting_started.rst b/doc/manual/getting_started.rst
index 84024d466..eb3166f6c 100644
--- a/doc/manual/getting_started.rst
+++ b/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
 --------------------