primitives/irq_event.py added. Document ISR interfacing.

Author: peterhinch

v3/docs/DRIVERS.md

@@ -11,6 +11,9 @@ events.
 The asynchronous ADC supports pausing a task until the value read from an ADC
 goes outside defined bounds.
 
+An IRQ_EVENT class provides a means of interfacing uasyncio to hard or soft
+interrupt service routines.
+
 # 1. Contents
 
  1. [Contents](./DRIVERS.md#1-contents)  
@@ -24,9 +27,10 @@ goes outside defined bounds.
  5. [ADC monitoring](./DRIVERS.md#5-adc-monitoring) Pause until an ADC goes out of bounds  
   5.1 [AADC class](./DRIVERS.md#51-aadc-class)  
   5.2 [Design note](./DRIVERS.md#52-design-note)  
- 6. [Additional functions](./DRIVERS.md#6-additional-functions)  
-  6.1 [launch](./DRIVERS.md#61-launch) Run a coro or callback interchangeably  
-  6.2 [set_global_exception](./DRIVERS.md#62-set_global_exception) Simplify debugging with a global exception handler  
+ 6. [IRQ_EVENT](./DRIVERS.md#6-irq_event)
+ 7. [Additional functions](./DRIVERS.md#6-additional-functions)  
+  7.1 [launch](./DRIVERS.md#71-launch) Run a coro or callback interchangeably  
+  7.2 [set_global_exception](./DRIVERS.md#72-set_global_exception) Simplify debugging with a global exception handler  
 
 ###### [Tutorial](./TUTORIAL.md#contents)
 
@@ -331,9 +335,95 @@ this for applications requiring rapid response.
 
 ###### [Contents](./DRIVERS.md#1-contents)
 
-# 6. Additional functions
+# 6. IRQ_EVENT
+
+Interfacing an interrupt service routine to `uasyncio` requires care. It is
+invalid to issue `create_task` or to trigger an `Event` in an ISR as it can
+cause a race condition in the scheduler. It is intended that `Event` will
+become compatible with soft IRQ's in a future revison of `uasyncio`.
+
+Currently there are two ways of interfacing hard or soft IRQ's with `uasyncio`.
+One is to use a busy-wait loop as per the
+[Message](https://github.com/peterhinch/micropython-async/blob/master/v3/docs/TUTORIAL.md#36-message)
+primitive. A more efficient approach is to use this `IRQ_EVENT` class. The API
+is a subset of the  `Event` class, so if official `Event` becomes thread-safe
+it may readily be substituted. The `IRQ_EVENT` class uses uses the `uasyncio`
+I/O mechanism to achieve thread-safe operation.
+
+Unlike `Event` only one task can wait on an `IRQ_EVENT`.
+
+Constructor:
+ * This has no args.
+
+Synchronous Methods:
+ * `set()` Initiates the event. May be called from a hard or soft ISR. Returns
+ fast.
+ * `is_set()` Returns `True` if the irq_event is set.
+ * `clear()` This does nothing; its purpose is to enable code to be written
+ compatible with a future thread-safe `Event` class, with the ISR setting then
+ immediately clearing the event.
+
+Asynchronous Method:
+ * `wait` Pause until irq_event is set. The irq_event is cleared.
+
+A single task waits on the event by issuing `await irq_event.wait()`; execution
+pauses until the ISR issues `irq_event.set()`. Execution of the paused task
+resumes when it is next scheduled. Under current `uasyncio` (V3.0.0) scheduling
+of the paused task does not occur any faster than using busy-wait. In typical
+use the ISR services the interrupting device, saving received data, then sets
+the irq_event to trigger processing of the received data.
+
+If interrupts occur faster than `uasyncio` can schedule the paused task, more
+than one interrupt may occur before the paused task runs.
+
+Example usage (assumes a Pyboard with pins X1 and X2 linked):
+```python
+from machine import Pin
+from pyb import LED
+import uasyncio as asyncio
+import micropython
+from primitives.irq_event import IRQ_EVENT
+
+micropython.alloc_emergency_exception_buf(100)
+
+driver = Pin(Pin.board.X2, Pin.OUT)
+receiver = Pin(Pin.board.X1, Pin.IN)
+evt_rx = IRQ_EVENT()  # IRQ_EVENT instance for receiving Pin
+
+def pin_han(pin):  # Hard IRQ handler. Typically services a device
+    evt_rx.set()  # then issues this which returns quickly
+
+receiver.irq(pin_han, Pin.IRQ_FALLING, hard=True)  # Set up hard ISR
+
+async def pulse_gen(pin):
+    while True:
+        await asyncio.sleep_ms(500)
+        pin(not pin())
+
+async def red_handler(evt_rx, iterations):
+    led = LED(1)
+    for x in range(iterations):
+        await evt_rx.wait()  # Pause until next interrupt
+        print(x)
+        led.toggle()
+
+async def irq_test(iterations):
+    pg = asyncio.create_task(pulse_gen(driver))
+    await red_handler(evt_rx, iterations)
+    pg.cancel()
+
+def test(iterations=20):
+    try:
+        asyncio.run(irq_test(iterations))
+    finally:
+        asyncio.new_event_loop()
+```
+
+###### [Contents](./DRIVERS.md#1-contents)
+
+# 7. Additional functions
 
-## 6.1 Launch
+## 7.1 Launch
 
 Importe as follows:
 ```python
@@ -345,7 +435,7 @@ runs it and returns the callback's return value. If a coro is passed, it is
 converted to a `task` and run asynchronously. The return value is the `task`
 instance. A usage example is in `primitives/switch.py`.
 
-## 6.2 set_global_exception
+## 7.2 set_global_exception
 
 Import as follows:
 ```python

v3/docs/TUTORIAL.md

@@ -35,7 +35,7 @@ REPL.
   3.7 [Barrier](./TUTORIAL.md#37-barrier)  
   3.8 [Delay_ms](./TUTORIAL.md#38-delay_ms-class) Software retriggerable delay.  
   3.9 [Synchronising to hardware](./TUTORIAL.md#39-synchronising-to-hardware)
-  Debouncing switches and pushbuttons. Taming ADC's.  
+  Debouncing switches and pushbuttons. Taming ADC's. Interfacing interrupts.  
  4. [Designing classes for asyncio](./TUTORIAL.md#4-designing-classes-for-asyncio)  
   4.1 [Awaitable classes](./TUTORIAL.md#41-awaitable-classes)  
        4.1.1 [Use in context managers](./TUTORIAL.md#411-use-in-context-managers)  
@@ -879,22 +879,30 @@ asyncio.run(queue_go(4))
 
 This is an unofficial primitive with no counterpart in CPython asyncio.
 
-This is similar to the `Event` class. It provides the following:
+This is similar to the `Event` class. It differs in that:
  * `.set()` has an optional data payload.
  * `.set()` is capable of being called from a hard or soft interrupt service
  routine - a feature not yet available in the more efficient official `Event`.
  * It is an awaitable class.
 
-The `.set()` method can accept an optional data value of any type. A task
+For interfacing to interrupt service routines see also
+[the IRQ_EVENT class](./DRIVERS.md#6-irq_event) which is more efficient but
+lacks the payload feature.
+
+Limitation: `Message` is intended for 1:1 operation where a single task waits
+on a message from another task or ISR. The receiving task should issue
+`.clear`.
+
+The `.set()` method can accept an optional data value of any type. The task
 waiting on the `Message` can retrieve it by means of `.value()`. Note that
 `.clear()` will set the value to `None`. One use for this is for the task
-setting the `Message` to issue `.set(utime.ticks_ms())`. A task waiting on the
-`Message` can determine the latency incurred, for example to perform
+setting the `Message` to issue `.set(utime.ticks_ms())`. The task waiting on
+the `Message` can determine the latency incurred, for example to perform
 compensation for this.
 
-Like `Event`, `Message` provides a way for one or more tasks to pause until
-another flags them to continue. A `Message` object is instantiated and made
-accessible to all tasks using it:
+Like `Event`, `Message` provides a way a task to pause until another flags it
+to continue. A `Message` object is instantiated and made accessible to the task
+using it:
 
 ```python
 import uasyncio as asyncio
@@ -920,9 +928,16 @@ A `Message` can provide a means of communication between an interrupt handler
 and a task. The handler services the hardware and issues `.set()` which is
 tested in slow time by the task.
 
-Currently its behaviour differs from that of `Event` where multiple tasks wait
-on a `Message`. This may change: it is therefore recommended to use `Message`
-instances with only one receiving task.
+Constructor:
+ * Optional arg `delay_ms=0` Polling interval.
+Synchronous methods:
+ * `set(data=None)` Trigger the message with optional payload.
+ * `is_set()` Return `True` if the message is set.
+ * `clear()` Clears the triggered status and sets payload to `None`.
+ * `value()` Return the payload.
+Asynchronous Method:
+ * `wait` Pause until message is triggered. You can also `await` the message as
+ per the above example.
 
 ###### [Contents](./TUTORIAL.md#contents)
 
@@ -1110,6 +1125,9 @@ The following hardware-related classes are documented [here](./DRIVERS.md):
  * `AADC` Asynchronous ADC. A task can pause until the value read from an ADC
  goes outside defined bounds. Bounds can be absolute or relative to the current
  value.
+ * `IRQ_EVENT` A way to interface between hard or soft interrupt service
+ routines and `uasyncio`. Discusses the hazards of apparently obvious ways such
+ as issuing `.create_task` or using the `Event` class.
 
 ###### [Contents](./TUTORIAL.md#contents)
 

v3/primitives/irq_event.py

@@ -0,0 +1,43 @@
+# irq_event.py Interface between uasyncio and asynchronous events
+# A thread-safe class. API is a subset of Event.
+
+# Copyright (c) 2020 Peter Hinch
+# Released under the MIT License (MIT) - see LICENSE file
+
+import uasyncio as asyncio
+import io
+
+MP_STREAM_POLL_RD = const(1)
+MP_STREAM_POLL = const(3)
+MP_STREAM_ERROR = const(-1)
+
+class IRQ_EVENT(io.IOBase):
+    def __init__(self):
+        self.state = False  # False=unset; True=set
+        self.sreader = asyncio.StreamReader(self)
+
+    def wait(self):
+        await self.sreader.readline()
+        self.state = False
+
+    def set(self):
+        self.state = True
+        return self
+
+    def is_set(self):
+        return self.state
+
+    def readline(self):
+        return b'\n'
+
+    def clear(self):
+        pass  # See docs
+
+    def ioctl(self, req, arg):
+        ret = MP_STREAM_ERROR
+        if req == MP_STREAM_POLL:
+            ret = 0
+            if arg & MP_STREAM_POLL_RD:
+                if self.state:
+                    ret |= MP_STREAM_POLL_RD
+        return ret

v3/primitives/message.py

@@ -16,7 +16,8 @@
 # message.clear() should be issued
 
 # This more efficient version is commented out because Event.set is not ISR
-# friendly. TODO If it gets fixed, reinstate this (tested) version.
+# friendly. TODO If it gets fixed, reinstate this (tested) version and update
+# tutorial for 1:n operation.
 #class Message(asyncio.Event):
     #def __init__(self, _=0):
         #self._data = None

v3/primitives/tests/irq_event_test.py

@@ -0,0 +1,57 @@
+# irq_event_test.py Test for irq_event class
+# Run on Pyboard with link between X1 and X2
+
+# Copyright (c) 2020 Peter Hinch
+# Released under the MIT License (MIT) - see LICENSE file
+
+# from primitives.tests.irq_event_test import test
+# test()
+
+from machine import Pin
+from pyb import LED
+import uasyncio as asyncio
+import micropython
+from primitives.irq_event import IRQ_EVENT
+
+def printexp():
+    print('Test expects a Pyboard with X1 and X2 linked. Expected output:')
+    print('\x1b[32m')
+    print('Flashes red LED and prints numbers 0-19')
+    print('\x1b[39m')
+    print('Runtime: 20s')
+
+printexp()
+
+micropython.alloc_emergency_exception_buf(100)
+
+driver = Pin(Pin.board.X2, Pin.OUT)
+receiver = Pin(Pin.board.X1, Pin.IN)
+evt_rx = IRQ_EVENT()
+
+def pin_han(pin):
+    evt_rx.set()
+
+receiver.irq(pin_han, Pin.IRQ_FALLING, hard=True)
+
+async def pulse_gen(pin):
+    while True:
+        await asyncio.sleep_ms(500)
+        pin(not pin())
+
+async def red_handler(evt_rx):
+    led = LED(1)
+    for x in range(20):
+        await evt_rx.wait()
+        print(x)
+        led.toggle()
+
+async def irq_test():
+    pg = asyncio.create_task(pulse_gen(driver))
+    await red_handler(evt_rx)
+    pg.cancel()
+
+def test():
+    try:
+        asyncio.run(irq_test())
+    finally:
+        asyncio.new_event_loop()