monitor: add SPI interface support.

Author: peterhinch

v3/as_demos/monitor/README.md

@@ -3,40 +3,70 @@
 This library provides a means of examining the behaviour of a running
 `uasyncio` system. The device under test is linked to a Raspberry Pi Pico. The
 latter displays the behaviour of the host by pin changes and/or optional print
-statements. Communication with the Pico is uni-directional via a UART so only a
-single GPIO pin is used - at last a use for the ESP8266 transmit-only UART(1).
+statements. A logic analyser or scope provides an insight into the way an
+asynchronous application is working.
 
-A logic analyser or scope provides an insight into the way an asynchronous
-application is working.
+Communication with the Pico may be by UART or SPI, and is uni-directional from
+system under test to Pico. If a UART is used only one GPIO pin is used; at last
+a use for the ESP8266 transmit-only UART(1). SPI requires three - mosi, sck and
+cs/.
 
 Where an application runs multiple concurrent tasks it can be difficult to
 locate a task which is hogging CPU time. Long blocking periods can also result
 from several tasks each of which can block for a period. If, on occasion, these
 are scheduled in succession, the times can add. The monitor issues a trigger
-when the blocking period exceeds a threshold. With a logic analyser the system
-state at the time of the transient event may be examined.
+pulse when the blocking period exceeds a threshold. With a logic analyser the
+system state at the time of the transient event may 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
 02 shows the fast running `hog_detect` task which cannot run at the time of the
-trigger. Lines 01 and 03 show the `foo` and `bar` tasks.  
+trigger because another task is hogging the CPU. Lines 01 and 03 show the `foo`
+and `bar` tasks.  
 ![Image](./monitor.jpg)
 
+### Breaking changes to support SPI
+
+The `set_uart` method is replaced by `set_device`. Pin mappings on the Pico
+have changed.
+
 ## 1.1 Pre-requisites
 
 The device being monitored must run firmware V1.17 or later. The `uasyncio`
-version should be V3 (as included in the firmware).
+version should be V3 (included in the firmware).
 
 ## 1.2 Usage
 
-Example script `quick_test.py` provides a usage example.
+Example script `quick_test.py` provides a usage example. It may be adapted to
+use a UART or SPI interface: see commented-out code.
+
+### 1.2.1 Interface selection set_device()
 
-An application to be monitored typically has the following setup code:
+An application to be monitored needs setup code to initialise the interface.
+This comprises a call to `monitor.set_device` with an initialised UART or SPI
+device. The Pico must be set up to match the interface chosen on the host: see
+[section 4](./README.md#4-the-pico-code).
+
+In the case of a UART an initialised UART with 1MHz baudrate is passed:
+```python
+from machine import UART
+from monitor import monitor, monitor_init, hog_detect, set_device
+set_device(UART(2, 1_000_000))  # Baudrate MUST be 1MHz.
+```
+In the case of SPI initialised SPI and cs/ Pin instances are passed:
 ```python
-from monitor import monitor, monitor_init, hog_detect, set_uart
-set_uart(2)  # Define device under test UART no.
+from machine import Pin, SPI
+from monitor import monitor, monitor_init, hog_detect, set_device
+set_device(SPI(2, baudrate=5_000_000), Pin('X6', Pin.OUT))  # Device under test SPI
 ```
-On application start it should issue
+The SPI instance must have default args; the one exception being baudrate which
+may be any value. I have tested up to 30MHz but there is no benefit in running
+above 1MHz. Hard or soft SPI may be used. It should be possible to share the
+bus with other devices, although I haven't tested this.
+
+### 1.2.2 Monitoring
+
+On startup, after defining the interface, an application should issue:
 ```python
 monitor_init()
 ```
@@ -52,14 +82,14 @@ The decorator args are as follows:
  2. An optional arg defining the maximum number of concurrent instances of the
  task to be independently monitored (default 1).
 
-Whenever the code runs, a pin on the Pico will go high, and when the code
+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
 viewed on a logic analyser or via console output on the Pico. This behavior
 works whether the code terminates normally, is cancelled or has a timeout.
 
 In the example above, when `my_coro` starts, the pin defined by `ident==2`
-(GPIO 4) will go high. When it ends, the pin will go low. If, while it is
-running, a second instance of `my_coro` is launched, the next pin (GPIO 5) will
+(GPIO 5) will go high. When it ends, the pin will go low. If, while it is
+running, a second instance of `my_coro` is launched, the next pin (GPIO 6) will
 go high. Pins will go low when the relevant instance terminates, is cancelled,
 or times out. If more instances are started than were specified to the
 decorator, a warning will be printed on the host. All excess instances will be
@@ -87,9 +117,9 @@ will cause the pin to go high for 30s, even though the task is consuming no
 resources for that period.
 
 To provide a clue about CPU hogging, a `hog_detect` coroutine is provided. This
-has `ident=0` and, if used, is monitored on GPIO 2. It loops, yielding to the
+has `ident=0` and, if used, is monitored on GPIO 3. It loops, yielding to the
 scheduler. It will therefore be scheduled in round-robin fashion at speed. If
-long gaps appear in the pulses on GPIO 2, other tasks are hogging the CPU.
+long gaps appear in the pulses on GPIO 3, other tasks are hogging the CPU.
 Usage of this is optional. To use, issue
 ```python
 import uasyncio as asyncio
@@ -139,55 +169,61 @@ It is advisable not to use the context manager with a function having the
 
 # 3. Pico Pin mapping
 
-The Pico GPIO numbers start at 2 to allow for UART(0) and also have a gap where
-GPIO's are used for particular purposes. This is the mapping between `ident`
-GPIO no. and Pico PCB pin, with the pins for the timer and the UART link also
+The Pico GPIO numbers used by idents start at 3 and have a gap where the Pico
+uses GPIO's for particular purposes. This is the mapping between `ident` GPIO
+no. and Pico PCB pin. Pins for the timer and the UART/SPI link are also
 identified:
 
-| ident | GPIO | pin  |
-|:-----:|:----:|:----:|
-| uart  |   1  |   2  |
-|   0   |   2  |   4  |
-|   1   |   3  |   5  |
-|   2   |   4  |   6  |
-|   3   |   5  |   7  |
-|   4   |   6  |   9  |
-|   5   |   7  |  10  |
-|   6   |   8  |  11  |
-|   7   |   9  |  12  |
-|   8   |  10  |  14  |
-|   9   |  11  |  15  |
-|  10   |  12  |  16  |
-|  11   |  13  |  17  |
-|  12   |  14  |  19  |
-|  13   |  15  |  20  |
-|  14   |  16  |  21  |
-|  15   |  17  |  22  |
-|  16   |  18  |  24  |
-|  17   |  19  |  25  |
-|  18   |  20  |  26  |
-|  19   |  21  |  27  |
-|  20   |  22  |  29  |
-|  21   |  26  |  31  |
-|  22   |  27  |  32  |
-| timer |  28  |  34  |
-
-The host's UART `txd` pin should be connected to Pico GPIO 1 (pin 2). There
-must be a link between `Gnd` pins on the host and Pico.
+| ident   | GPIO | pin  |
+|:-------:|:----:|:----:|
+| nc/mosi |   0  |   1  |
+| rxd/sck |   1  |   2  |
+| nc/cs/  |   2  |   4  |
+|   0     |   3  |   5  |
+|   1     |   4  |   6  |
+|   2     |   5  |   7  |
+|   3     |   6  |   9  |
+|   4     |   7  |  10  |
+|   5     |   8  |  11  |
+|   6     |   9  |  12  |
+|   7     |  10  |  14  |
+|   8     |  11  |  15  |
+|   9     |  12  |  16  |
+|  10     |  13  |  17  |
+|  11     |  14  |  19  |
+|  12     |  15  |  20  |
+|  13     |  16  |  21  |
+|  14     |  17  |  22  |
+|  15     |  18  |  24  |
+|  16     |  19  |  25  |
+|  17     |  20  |  26  |
+|  18     |  21  |  27  |
+|  19     |  22  |  29  |
+|  20     |  26  |  31  |
+|  21     |  27  |  32  |
+| timer   |  28  |  34  |
+
+For a UART interface the host's UART `txd` pin should be connected to Pico GPIO
+1 (pin 2).
+
+For SPI the host's `mosi` goes to GPIO 0 (pin 1), and `sck` to GPIO 1 (pin 2).
+The host's CS Pin is connected to GPIO 2 (pin 4).
+
+There must be a link between `Gnd` pins on the host and Pico.
 
 # 4. The Pico code
 
-Monitoring of the UART with default behaviour is started as follows:
+Monitoring via the UART with default behaviour is started as follows:
 ```python
 from monitor_pico import run
 run()
 ```
 By default the Pico does not produce console output and the timer has a period
 of 100ms - pin 28 will pulse if ident 0 is inactive for over 100ms. These
 behaviours can be modified by the following `run` args:
- 1. `period=100` Define the timer period in ms.
+ 1. `period=100` Define the hog_detect timer period in ms.
  2. `verbose=()` Determines which `ident` values should produce console output.
- 3. `device="uart"` Provides for future use of other interfaces.
+ 3. `device="uart"` Set to "spi" for an SPI interface.
 
 Thus to run such that idents 4 and 7 produce console output, with hogging
 reported if blocking is for more than 60ms, issue
@@ -198,10 +234,12 @@ run(60, (4, 7))
 
 # 5. Performance and design notes
 
-The latency between a monitored coroutine starting to run and the Pico pin
-going high is about 20μs. This isn't as absurd as it sounds: theoretically the
-latency could be negative as the effect of the decorator is to send the
-character before the coroutine starts.
+Using a UART the latency between a monitored coroutine starting to run and the
+Pico pin going high is about 23μs. With SPI I measured -12μs. This isn't as
+absurd as it sounds: a negative latency is the effect of the decorator which
+sends the character before the coroutine starts. These values are small in the
+context of `uasyncio`: scheduling delays are on the order of 150μs or greater
+depending on the platform. See `quick_test.py` for a way to measure latency.
 
 The use of decorators is intended to ease debugging: they are readily turned on
 and off by commenting out.
@@ -219,11 +257,3 @@ which can be scheduled at a high rate, can't overflow the UART buffer. The
 
 This project was inspired by
 [this GitHub thread](https://github.com/micropython/micropython/issues/7456).
-
-# 6. Work in progress
-
-It is intended to add an option for SPI communication; `monitor.py` has a
-`set_device` method which can be passed an instance of an initialised SPI
-object. The Pico `run` method will be able to take a `device="spi"` arg which
-will expect an SPI connection on pins 0 (sck) and 1 (data). This requires a
-limited implementation of an SPI slave using the PIO, which I will do soon.

v3/as_demos/monitor/monitor.py

@@ -5,23 +5,37 @@
 # Released under the MIT License (MIT) - see LICENSE file
 
 import uasyncio as asyncio
-from machine import UART
+from machine import UART, SPI, Pin
 
-device = None
-def set_uart(n):  # Monitored app defines interface
-    global device
-    device = UART(n, 1_000_000)
+_write = lambda _ : print('Must run set_device')
+_dummy = lambda : None  # If UART do nothing.
 
-# For future use with SPI
-# Pass initialised instance of some device
-def set_device(dev):
-    global device
-    device = dev
+# For UART pass initialised UART. Baudrate must be 1_000_000.
+# For SPI pass initialised instance SPI. Can be any baudrate, but
+# must be default in other respects.
+def set_device(dev, cspin=None):
+    global _write
+    global _dummy
+    if isinstance(dev, UART) and cspin is None:  # UART
+        _write = dev.write
+    elif isinstance(dev, SPI) and isinstance(cspin, Pin):
+        cspin(1)
+        def spiwrite(data):
+            cspin(0)
+            dev.write(data)
+            cspin(1)
+        _write = spiwrite
+        def clear_sm():  # Set Pico SM to its initial state
+            cspin(1)
+            dev.write(b'\0')  # SM is now waiting for CS low.
+        _dummy = clear_sm
+    else:
+        print('set_device: invalid args.')
 
-_available = set(range(0, 23))  # Valid idents are 0..22
+_available = set(range(0, 22))  # Valid idents are 0..21
 
 def _validate(ident, num=1):
-    if ident >= 0 and ident + num <= 23:
+    if ident >= 0 and ident + num < 22:
         try:
             for x in range(ident, ident + num):
                 _available.remove(x)
@@ -44,22 +58,25 @@ async def wrapped_coro(*args, **kwargs):
             instance += 1
             if instance > max_instances:
                 print(f'Monitor {n:02} max_instances reached')
-            device.write(v)
+            _write(v)
             try:
                 res = await coro(*args, **kwargs)
             except asyncio.CancelledError:
                 raise
             finally:
                 d |= 0x20
                 v = bytes(chr(d), 'utf8')
-                device.write(v)
+                _write(v)
                 instance -= 1
             return res
         return wrapped_coro
     return decorator
 
+# If SPI, clears the state machine in case prior test resulted in the DUT
+# crashing. It does this by sending a byte with CS\ False (high).
 def monitor_init():
-    device.write(b'z')
+    _dummy()  # Does nothing if UART
+    _write(b'z')
 
 # Optionally run this to show up periods of blocking behaviour
 @monitor(0)
@@ -79,9 +96,9 @@ def decorator(func):
         dend = 0x60 + n
         vend = bytes(chr(dend), 'utf8')
         def wrapped_func(*args, **kwargs):
-            device.write(vstart)
+            _write(vstart)
             res = func(*args, **kwargs)
-            device.write(vend)
+            _write(vend)
             return res
         return wrapped_func
     return decorator
@@ -98,9 +115,9 @@ def __init__(self, n):
         self.vend = bytes(chr(self.dend), 'utf8')
 
     def __enter__(self):
-        device.write(self.vstart)
+        _write(self.vstart)
         return self
 
     def __exit__(self, type, value, traceback):
-        device.write(self.vend)
+        _write(self.vend)
         return False  # Don't silence exceptions