ports/nrf: Upmerging port with upstream master

3 files changed, 33 insertions, 6 deletions

diff --git a/docs/reference/constrained.rst b/docs/reference/constrained.rst
index 14286aa26..e7de459bc 100644
--- a/docs/reference/constrained.rst
+++ b/docs/reference/constrained.rst
@@ -279,7 +279,7 @@ After importing the modules, execute:
 
 Then copy and paste all the Q(xxx) lines into a text editor. Check for and
 remove lines which are obviously invalid. Open the file qstrdefsport.h which
-will be found in stmhal (or the equivalent directory for the architecture in
+will be found in ports/stm32 (or the equivalent directory for the architecture in
 use). Copy and paste the corrected lines at the end of the file. Save the file,
 rebuild and flash the firmware. The outcome can be checked by importing the
 modules and again issuing:
diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst
index 4099ae951..4cd3d84cc 100644
--- a/docs/reference/glossary.rst
+++ b/docs/reference/glossary.rst
@@ -54,11 +54,11 @@ Glossary
         separate project
         `micropython-lib <https://github.com/micropython/micropython-lib>`_
         which provides implementations for many modules from CPython's
-        standard library. However, large subset of these modules required
+        standard library. However, large subset of these modules require
         POSIX-like environment (Linux, MacOS, Windows may be partially
-        supported), and thus would work or make sense only with MicroPython
-        Unix port. Some subset of modules however usable for baremetal ports
-        too.
+        supported), and thus would work or make sense only with
+        `MicroPython Unix port`. Some subset of modules is however usable
+        for `baremetal` ports too.
 
         Unlike monolithic :term:`CPython` stdlib, micropython-lib modules
         are intended to be installed individually - either using manual
@@ -68,7 +68,13 @@ Glossary
         MicroPython supports different :term:`boards <board>`, RTOSes,
         and OSes, and can be relatively easily adapted to new systems.
         MicroPython with support for a particular system is called a
-        "port" to that system.
+        "port" to that system. Different ports may have widely different
+        functionality. This documentation is intended to be a reference
+        of the generic APIs available across different ports ("MicroPython
+        core"). Note that some ports may still omit some APIs described
+        here (e.g. due to resource constraints). Any such differences,
+        and port-specific extensions beyond MicroPython core functionality,
+        would be described in the separate port-specific documentation.
 
     MicroPython Unix port
         Unix port is one of the major :term:`MicroPython ports <MicroPython port>`.
diff --git a/docs/reference/isr_rules.rst b/docs/reference/isr_rules.rst
index 23dcfd01f..5009f30f7 100644
--- a/docs/reference/isr_rules.rst
+++ b/docs/reference/isr_rules.rst
@@ -21,6 +21,7 @@ This summarises the points detailed below and lists the principal recommendation
 
 * Keep the code as short and simple as possible.
 * Avoid memory allocation: no appending to lists or insertion into dictionaries, no floating point.
+* Consider using ``micropython.schedule`` to work around the above constraint.
 * Where an ISR returns multiple bytes use a pre-allocated ``bytearray``. If multiple integers are to be
   shared between an ISR and the main program consider an array (``array.array``).
 * Where data is shared between the main program and an ISR, consider disabling interrupts prior to accessing
@@ -158,6 +159,26 @@ On platforms with hardware floating point (such as the Pyboard) the inline ARM T
 round this limitation. This is because the processor stores float values in a machine word; values can be shared
 between the ISR and main program code via an array of floats.
 
+Using micropython.schedule
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This function enables an ISR to schedule a callback for execution "very soon". The callback is queued for
+execution which will take place at a time when the heap is not locked. Hence it can create Python objects
+and use floats. The callback is also guaranteed to run at a time when the main program has completed any
+update of Python objects, so the callback will not encounter partially updated objects.
+
+Typical usage is to handle sensor hardware. The ISR acquires data from the hardware and enables it to
+issue a further interrupt. It then schedules a callback to process the data.
+
+Scheduled callbacks should comply with the principles of interrupt handler design outlined below. This is to
+avoid problems resulting from I/O activity and the modification of shared data which can arise in any code
+which pre-empts the main program loop.
+
+Execution time needs to be considered in relation to the frequency with which interrupts can occur. If an
+interrupt occurs while the previous callback is executing, a further instance of the callback will be queued
+for execution; this will run after the current instance has completed. A sustained high interrupt repetition
+rate therefore carries a risk of unconstrained queue growth and eventual failure with a ``RuntimeError``.
+
 Exceptions
 ----------