monitor: Fix bug. README imrovements.

peterhinch · peterhinch · commit dbb46bcc7ed8 · 2021-10-19T13:59:41.000+01:00
diff --git a/v3/as_demos/monitor/README.md b/v3/as_demos/monitor/README.md
@@ -18,13 +18,9 @@ when the blocking period exceeds a threshold. The threshold can be a fixed time
 or the current maximum blocking period. A logic analyser enables the state at
 the time of the transient event to be examined.
 
-The following image shows the `quick_test.py` code being monitored at the point
-when a task hogs the CPU. The top line 00 shows the "hog detect" trigger. Line
-01 shows the fast running `hog_detect` task which cannot run at the time of the
-trigger because another task is hogging the CPU. Lines 02 and 04 show the `foo`
-and `bar` tasks. Line 03 shows the `hog` task and line 05 is a trigger issued
-by `hog()` when it starts monopolising the CPU. The Pico issues the "hog
-detect" trigger 100ms after hogging starts.  
+This image shows the detection of CPU hogging. A trigger pulse is generated
+100ms after hogging caused the scheduler to be unable to schedule tasks. It is
+discussed in more detail in [section 6](./README.md#6-test-and-demo-scripts).
 
 ![Image](./monitor.jpg)
 
@@ -37,8 +33,8 @@ to demonstrate that this never exceeded 5ms.
 ## 1.1 Concepts
 
 Communication with the Pico may be by UART or SPI, and is uni-directional from
-DUT to Pico. If a UART is used only one GPIO pin is needed. SPI requires three
-- `mosi`, `sck` and `cs/`.
+DUT to Pico. If a UART is used only one GPIO pin is needed. SPI requires three,
+namely `mosi`, `sck` and `cs/`.
 
 The Pico runs the following:
 ```python
@@ -189,8 +185,7 @@ crashed, was interrupted or failed.
 
 Re-using idents would lead to confusing behaviour. If an ident is out of range
 or is assigned to more than one coroutine an error message is printed and
-execution terminates. See [section 7.3](./README.md#73-validation) for a
-special case where validation must be defeated.
+execution terminates.
 
 # 3. Monitoring uasyncio code
 
@@ -210,6 +205,9 @@ The decorator positional args are as follows:
  task to be independently monitored (default 1).
  3. `verbose=True` If `False` suppress the warning which is printed on the DUT
  if the instance count exceeds `max_instances`.
+ 4. `looping=False` Set `True` if the decorator is called repeatedly e.g.
+ decorating a nested function or method. The `True` value ensures validation of
+ the ident occurs once only when the decorator first runs.
 
 Whenever the coroutine runs, a pin on the Pico will go high, and when the code
 terminates it will go low. This enables the behaviour of the system to be
@@ -261,13 +259,13 @@ import monitor
 asyncio.create_task(monitor.hog_detect())
 # code omitted
 ```
-To aid in detecting the gaps in execution, the Pico code implements a timer.
-This is retriggered by activity on `ident=0`. If it times out, a brief high
-going pulse is produced on GPIO 28, along with the console message "Hog". The
-pulse can be used to trigger a scope or logic analyser. The duration of the
-timer may be adjusted. Other modes of hog detection are also supported, notably
-producing a trigger pulse only when the prior maximum was exceeded. See
-[section 4](./README.md~4-the-pico-code).
+To aid in detecting the gaps in execution, in its default mode the Pico code
+implements a timer. This is retriggered by activity on `ident=0`. If it times
+out, a brief high going pulse is produced on GPIO 28, along with the console
+message "Hog". The pulse can be used to trigger a scope or logic analyser. The
+duration of the timer may be adjusted. Other modes of hog detection are also
+supported, notably producing a trigger pulse only when the prior maximum was
+exceeded. See [section 5](./README.md#5-Pico).
 
 # 4. Monitoring arbitrary code
 
@@ -292,13 +290,17 @@ duration of every call to `sync_func()`:
 def sync_func():
     pass
 ```
+Decorator args:
+ 1. `ident`
+ 2. `looping=False` Set `True` if the decorator is called repeatedly e.g. in a
+ nested function or method. The `True` value ensures validation of  the ident
+ occurs once only when the decorator first runs.
 
 ## 4.2 The mon_call context manager
 
 This may be used to monitor a function only when called from specific points in
-the code. Validation of idents is looser here because a context manager is
-often used in a looping construct: it seems impractical to distinguish this
-case from that where two context managers are instantiated with the same ID.
+the code. Since context managers may be used in a looping construct the ident
+is only checked for conflicts when the CM is first instantiated.
 
 Usage:
 ```python
@@ -319,8 +321,7 @@ is created by passing the ident. If the instance is run with no args a brief
 (~80μs) pulse will occur on the Pico pin. If `True` is passed, the pin will go
 high until `False` is passed.
 
-The closure should be instantiated once only. If instantiated in a loop the
-ident will fail the check on re-use.
+The closure should be instantiated once only in the outermost scope.
 ```python
 trig = monitor.trigger(10)  # Associate trig with ident 10.
 
@@ -335,10 +336,10 @@ def bar():
 ## 4.4 Timing of code segments
 
 It can be useful to time the execution of a specific block of code especially
-if the time varies. It is possible to cause a message to be printed and a
-trigger pulse to be generated whenever the execution time exceeds the prior
-maximum. The scope or logic analyser may be triggered by this pulse allowing
-the state of other parts of the system to be checked.
+if the duration varies in real time. It is possible to cause a message to be
+printed and a trigger pulse to be generated whenever the execution time exceeds
+the prior maximum. A scope or logic analyser may be triggered by this pulse
+allowing the state of other components of the system to be checked.
 
 This is done by re-purposing ident 0 as follows:
 ```python
@@ -467,13 +468,21 @@ from monitor_pico import run, WIDTH
 run((20, WIDTH))  # Ignore widths < 20ms. 
 ```
 Assuming that ident 0 is used as described in
-[section 4.4](./README.md#44-timing-of-code-segments) a trigger pulse on GPIO28
+[section 5.5](./README.md#55-timing-of-code-segments) a trigger pulse on GPIO28
 will occur each time the time taken exceeds both 20ms and its prior maximum. A
 message with the actual width is also printed whenever this occurs.
 
 # 6. Test and demo scripts
 
-`quick_test.py` Primarily tests deliberate CPU hogging. Discussed in section 1.
+The following image shows the `quick_test.py` code being monitored at the point
+when a task hogs the CPU. The top line 00 shows the "hog detect" trigger. Line
+01 shows the fast running `hog_detect` task which cannot run at the time of the
+trigger because another task is hogging the CPU. Lines 02 and 04 show the `foo`
+and `bar` tasks. Line 03 shows the `hog` task and line 05 is a trigger issued
+by `hog()` when it starts monopolising the CPU. The Pico issues the "hog
+detect" trigger 100ms after hogging starts.  
+
+![Image](./monitor.jpg)
 
 `full_test.py` Tests task timeout and cancellation, also the handling of
 multiple task instances. If the Pico is run with `run((1, MAX))` it reveals
@@ -508,6 +517,8 @@ in `hog_detect` show the periods of deliberate CPU hogging.
 `syn_time.py` Demonstrates timing of a specific code segment with a trigger
 pulse being generated every time the period exceeds its prior maximum.
 
+![Image](./tests/syn_time.jpg)
+
 # 7. Internals
 
 ## 7.1 Performance and design notes
@@ -573,21 +584,7 @@ In the following, `thresh` is the time passed to `run()` in `period[0]`.
  * `MAX` Trigger occurs if period exceeds `thresh` and also exceeds the prior
  maximum.
 
-This project was inspired by
-[this GitHub thread](https://github.com/micropython/micropython/issues/7456).
-
-## 7.3 Validation
-
-The `monitor` module attempts to protect against inadvertent multiple use of an
-`ident`. There are use patterns which are incompatible with this, notably where
-a decorated function or coroutine is instantiated in a looping construct. To
-cater for such cases validation can be defeated. This is done by issuing:
-```python
-import monitor
-monitor.validation(False)
-```
-
-## 7.4 ESP8266 note
+## 7.3 ESP8266 note
 
 ESP8266 applications can be monitored using the transmit-only UART 1.
 
@@ -610,3 +607,6 @@ device under test is on the right, linked to the Pico board by means of a UART.
 ![Image](./monitor_hw.JPG)
 
 I can supply a schematic and PCB details if anyone is interested.
+
+This project was inspired by
+[this GitHub thread](https://github.com/micropython/micropython/issues/7456).
diff --git a/v3/as_demos/monitor/monitor.py b/v3/as_demos/monitor/monitor.py
@@ -45,33 +45,34 @@ def clear_sm():  # Set Pico SM to its initial state
         _quit("set_device: invalid args.")
 
 
-# Justification for validation even when decorating a method
 # /mnt/qnap2/data/Projects/Python/AssortedTechniques/decorators
 _available = set(range(0, 22))  # Valid idents are 0..21
-_do_validate = True
-
-
-def _validate(ident, num=1):
-    if _do_validate:
-        if ident >= 0 and ident + num < 22:
-            try:
-                for x in range(ident, ident + num):
+# Looping: some idents may be repeatedly instantiated. This can occur
+# if decorator is run in looping code. A CM is likely to be used in a
+# loop. In these cases only validate on first use.
+_loopers = set()
+
+
+def _validate(ident, num=1, looping=False):
+    if ident >= 0 and ident + num < 22:
+        try:
+            for x in range(ident, ident + num):
+                if looping:
+                    if x not in _loopers:
+                        _available.remove(x)
+                        _loopers.add(x)
+                else:
                     _available.remove(x)
-            except KeyError:
-                _quit("error - ident {:02d} already allocated.".format(x))
-        else:
-            _quit("error - ident {:02d} out of range.".format(ident))
-
-
-def validation(do=True):
-    global _do_validate
-    _do_validate = do
+        except KeyError:
+            _quit("error - ident {:02d} already allocated.".format(x))
+    else:
+        _quit("error - ident {:02d} out of range.".format(ident))
 
 
 # asynchronous monitor
-def asyn(n, max_instances=1, verbose=True):
+def asyn(n, max_instances=1, verbose=True, looping=False):
     def decorator(coro):
-        _validate(n, max_instances)
+        _validate(n, max_instances, looping)
         instance = 0
 
         async def wrapped_coro(*args, **kwargs):
@@ -114,11 +115,11 @@ async def hog_detect(s=(b"\x40", b"\x60")):
 
 
 # Monitor a synchronous function definition
-def sync(n):
+def sync(ident, looping=False):
     def decorator(func):
-        _validate(n)
-        vstart = int.to_bytes(0x40 + n, 1, "big")
-        vend = int.to_bytes(0x60 + n, 1, "big")
+        _validate(ident, 1, looping)
+        vstart = int.to_bytes(0x40 + ident, 1, "big")
+        vend = int.to_bytes(0x60 + ident, 1, "big")
 
         def wrapped_func(*args, **kwargs):
             _write(vstart)
@@ -133,12 +134,9 @@ def wrapped_func(*args, **kwargs):
 
 # Monitor a function call
 class mon_call:
-    _cm_idents = set()  # Idents used by this CM
-
     def __init__(self, n):
-        if n not in self._cm_idents:  # ID can't clash with other objects
-            _validate(n)  # but could have two CM's with same ident
-            self._cm_idents.add(n)
+        # looping: a CM may be instantiated many times
+        _validate(n, 1, True)
         self.vstart = int.to_bytes(0x40 + n, 1, "big")
         self.vend = int.to_bytes(0x60 + n, 1, "big")
 
@@ -152,7 +150,7 @@ def __exit__(self, type, value, traceback):
 
 
 # Either cause pico ident n to produce a brief (~80μs) pulse or turn it
-# on or off on demand.
+# on or off on demand. No looping: docs suggest instantiating at start.
 def trigger(n):
     _validate(n)
     on = int.to_bytes(0x40 + n, 1, "big")
diff --git a/v3/as_demos/monitor/tests/looping.py b/v3/as_demos/monitor/tests/looping.py
@@ -0,0 +1,58 @@
+# syn_test.py
+# Tests the monitoring synchronous code and of an async method.
+
+# Copyright (c) 2021 Peter Hinch
+# Released under the MIT License (MIT) - see LICENSE file
+
+import uasyncio as asyncio
+import time
+from machine import Pin, UART, SPI
+import monitor
+
+# Define interface to use
+monitor.set_device(UART(2, 1_000_000))  # UART must be 1MHz
+# monitor.set_device(SPI(2, baudrate=5_000_000), Pin('X1', Pin.OUT))  # SPI suggest >= 1MHz
+trig = monitor.trigger(5)
+
+
+class Foo:
+    def __init__(self):
+        pass
+
+    @monitor.asyn(1, 2)  # ident 1/2 high
+    async def pause(self):
+        while True:
+            trig()
+            self.wait1()  # ident 3 10ms pulse
+            await asyncio.sleep_ms(100)
+            with monitor.mon_call(4):  # ident 4 10ms pulse
+                self.wait2()
+            await asyncio.sleep_ms(100)
+            # ident 1/2 low
+
+    async def bar(self):
+        @monitor.asyn(3, looping = True)
+        async def wait1():
+            await asyncio.sleep_ms(100)
+        @monitor.sync(4, True)
+        def wait2():
+            time.sleep_ms(10)
+        trig()
+        await wait1()
+        trig()
+        wait2()
+
+
+async def main():
+    monitor.init()
+    asyncio.create_task(monitor.hog_detect())  # Make 10ms waitx gaps visible
+    foo = Foo()
+    while True:
+        await foo.bar()
+        await asyncio.sleep_ms(100)
+    await foo.pause()
+
+try:
+    asyncio.run(main())
+finally:
+    asyncio.new_event_loop()
diff --git a/v3/as_demos/monitor/tests/syn_test.py b/v3/as_demos/monitor/tests/syn_test.py
@@ -12,6 +12,7 @@
 # Define interface to use
 monitor.set_device(UART(2, 1_000_000))  # UART must be 1MHz
 # monitor.set_device(SPI(2, baudrate=5_000_000), Pin('X1', Pin.OUT))  # SPI suggest >= 1MHz
+trig = monitor.trigger(5)
 
 
 class Foo:
@@ -27,7 +28,7 @@ async def pause(self):
         await asyncio.sleep_ms(100)
         # ident 1/2 low
 
-    @monitor.sync(3)  # Decorator so ident not reserved
+    @monitor.sync(3)
     def wait1(self):
         time.sleep_ms(10)
 
@@ -39,7 +40,6 @@ async def main():
     asyncio.create_task(monitor.hog_detect())  # Make 10ms waitx gaps visible
     foo1 = Foo()
     foo2 = Foo()
-    trig = monitor.trigger(5)
     while True:
         trig()  # Mark start with pulse on ident 5
         # Create two instances of .pause separated by 50ms
diff --git a/v3/as_demos/monitor/tests/syn_time.jpg b/v3/as_demos/monitor/tests/syn_time.jpg
diff --git a/v3/as_demos/monitor/tests/syn_time.py b/v3/as_demos/monitor/tests/syn_time.py
@@ -0,0 +1,41 @@
+# syn_time.py
+# Tests the monitoring synchronous code.
+# Can run with run((1, monitor.WIDTH)) to check max width detection.
+
+# Copyright (c) 2021 Peter Hinch
+# Released under the MIT License (MIT) - see LICENSE file
+
+import uasyncio as asyncio
+import time
+from machine import Pin, UART, SPI
+import monitor
+
+# Define interface to use
+monitor.set_device(UART(2, 1_000_000))  # UART must be 1MHz
+# monitor.set_device(SPI(2, baudrate=5_000_000), Pin('X1', Pin.OUT))  # SPI suggest >= 1MHz
+
+trig0 = monitor.trigger(0)
+twait = 20
+
+async def test():
+    while True:
+        await asyncio.sleep_ms(100)
+        trig0(True)
+        await asyncio.sleep_ms(twait)
+        trig0(False)
+
+async def lengthen():
+    global twait
+    while twait < 200:
+        twait += 1
+        await asyncio.sleep(1)
+
+async def main():
+    monitor.init()
+    asyncio.create_task(lengthen())
+    await test()
+
+try:
+    asyncio.run(main())
+finally:
+    asyncio.new_event_loop()
