Merge commit 'f869d6b2e339c04469c6c9ea3fb2fabd7bbb2d8c' into nrf2_merge

This is prep for merging in the NRF5 pull request.

12 files changed, 117 insertions, 36 deletions

diff --git a/docs/esp8266/tutorial/neopixel.rst b/docs/esp8266/tutorial/neopixel.rst
index 245aed6d4..a1537526f 100644
--- a/docs/esp8266/tutorial/neopixel.rst
+++ b/docs/esp8266/tutorial/neopixel.rst
@@ -20,6 +20,20 @@ To set the colour of pixels use::
     >>> np[1] = (0, 128, 0) # set to green, half brightness
     >>> np[2] = (0, 0, 64)  # set to blue, quarter brightness
 
+For LEDs with more than 3 colours, such as RGBW pixels or RGBY pixels, the
+NeoPixel class takes a ``bpp`` parameter. To setup a NeoPixel object for an
+RGBW Pixel, do the following::
+
+    >>> import machine, neopixel
+    >>> np = neopixel.NeoPixel(machine.Pin(4), 8, bpp=4)
+
+In a 4-bpp mode, remember to use 4-tuples instead of 3-tuples to set the colour.
+For example to set the first three pixels use::
+
+    >>> np[0] = (255, 0, 0, 128) # Orange in an RGBY Setup
+    >>> np[1] = (0, 255, 0, 128) # Yellow-green in an RGBY Setup
+    >>> np[2] = (0, 0, 255, 128) # Green-blue in an RGBY Setup
+
 Then use the ``write()`` method to output the colours to the LEDs::
 
     >>> np.write()
diff --git a/docs/library/btree.rst b/docs/library/btree.rst
index 9322d32e6..8fac67e8d 100644
--- a/docs/library/btree.rst
+++ b/docs/library/btree.rst
@@ -76,20 +76,24 @@ Example::
 Functions
 ---------
 
-.. function:: open(stream, \*, flags=0, cachesize=0, pagesize=0, minkeypage=0)
+.. function:: open(stream, \*, flags=0, pagesize=0, cachesize=0, minkeypage=0)
 
    Open a database from a random-access `stream` (like an open file). All
    other parameters are optional and keyword-only, and allow to tweak advanced
    parameters of the database operation (most users will not need them):
 
    * *flags* - Currently unused.
-   * *cachesize* - Suggested maximum memory cache size in bytes. For a
-     board with enough memory using larger values may improve performance.
-     The value is only a recommendation, the module may use more memory if
-     values set too low.
    * *pagesize* - Page size used for the nodes in BTree. Acceptable range
-     is 512-65536. If 0, underlying I/O block size will be used (the best
-     compromise between memory usage and performance).
+     is 512-65536. If 0, a port-specific default will be used, optimized for
+     port's memory usage and/or performance.
+   * *cachesize* - Suggested memory cache size in bytes. For a
+     board with enough memory using larger values may improve performance.
+     Cache policy is as follows: entire cache is not allocated at once;
+     instead, accessing a new page in database will allocate a memory buffer
+     for it, until value specified by *cachesize* is reached. Then, these
+     buffers will be managed using LRU (least recently used) policy. More
+     buffers may still be allocated if needed (e.g., if a database contains
+     big keys and/or values). Allocated cache buffers aren't reclaimed.
    * *minkeypage* - Minimum number of keys to store per page. Default value
      of 0 equivalent to 2.
 
diff --git a/docs/library/framebuf.rst b/docs/library/framebuf.rst
index b92bd08ef..74c9f8564 100644
--- a/docs/library/framebuf.rst
+++ b/docs/library/framebuf.rst
@@ -38,9 +38,9 @@ Constructors
         - *width* is the width of the FrameBuffer in pixels
         - *height* is the height of the FrameBuffer in pixels
         - *format* specifies the type of pixel used in the FrameBuffer;
-          valid values are ``framebuf.MVLSB``, ``framebuf.RGB565``
-          and ``framebuf.GS4_HMSB``. MVLSB is monochrome 1-bit color,
-          RGB565 is RGB 16-bit color, and GS4_HMSB is grayscale 4-bit color.
+          permissible values are listed under Constants below. These set the
+          number of bits used to encode a color value and the layout of these
+          bits in *buffer*.
           Where a color value c is passed to a method, c is a small integer
           with an encoding that is dependent on the format of the FrameBuffer.
         - *stride* is the number of pixels between each horizontal line
@@ -110,8 +110,9 @@ Other methods
     corresponding color will be considered transparent: all pixels with that
     color value will not be drawn.
 
-    This method works between FrameBuffer's utilising different formats, but the
-    resulting colors may be unexpected due to the mismatch in color formats.
+    This method works between FrameBuffer instances utilising different formats,
+    but the resulting colors may be unexpected due to the mismatch in color
+    formats.
 
 Constants
 ---------
diff --git a/docs/library/machine.Signal.rst b/docs/library/machine.Signal.rst
index 486908627..a1a29164b 100644
--- a/docs/library/machine.Signal.rst
+++ b/docs/library/machine.Signal.rst
@@ -4,17 +4,44 @@
 class Signal -- control and sense external I/O devices
 ======================================================
 
-The Signal class is a simple extension of Pin class. Unlike Pin, which
+The Signal class is a simple extension of the `Pin` class. Unlike Pin, which
 can be only in "absolute" 0 and 1 states, a Signal can be in "asserted"
 (on) or "deasserted" (off) states, while being inverted (active-low) or
-not. Summing up, it adds logical inversion support to Pin functionality.
+not. In other words, it adds logical inversion support to Pin functionality.
 While this may seem a simple addition, it is exactly what is needed to
 support wide array of simple digital devices in a way portable across
 different boards, which is one of the major MicroPython goals. Regardless
-whether different users have an active-high or active-low LED, a normally
-open or normally closed relay - you can develop single, nicely looking
+of whether different users have an active-high or active-low LED, a normally
+open or normally closed relay - you can develop a single, nicely looking
 application which works with each of them, and capture hardware
-configuration differences in few lines on the config file of your app.
+configuration differences in few lines in the config file of your app.
+
+Example::
+
+    from machine import Pin, Signal
+
+    # Suppose you have an active-high LED on pin 0
+    led1_pin = Pin(0, Pin.OUT)
+    # ... and active-low LED on pin 1
+    led2_pin = Pin(1, Pin.OUT)
+
+    # Now to light up both of them using Pin class, you'll need to set
+    # them to different values
+    led1_pin.value(1)
+    led2_pin.value(0)
+
+    # Signal class allows to abstract away active-high/active-low
+    # difference
+    led1 = Signal(led1_pin, invert=False)
+    led2 = Signal(led2_pin, invert=True)
+
+    # Now lighting up them looks the same
+    led1.value(1)
+    led2.value(1)
+
+    # Even better:
+    led1.on()
+    led2.on()
 
 Following is the guide when Signal vs Pin should be used:
 
@@ -33,11 +60,11 @@ architecture of MicroPython: Pin offers the lowest overhead, which may
 be important when bit-banging protocols. But Signal adds additional
 flexibility on top of Pin, at the cost of minor overhead (much smaller
 than if you implemented active-high vs active-low device differences in
-Python manually!). Also, Pin is low-level object which needs to be
+Python manually!). Also, Pin is a low-level object which needs to be
 implemented for each support board, while Signal is a high-level object
 which comes for free once Pin is implemented.
 
-If in doubt, give the Signal a try! Once again, it is developed to save
+If in doubt, give the Signal a try! Once again, it is offered to save
 developers from the need to handle unexciting differences like active-low
 vs active-high signals, and allow other users to share and enjoy your
 application, instead of being frustrated by the fact that it doesn't
diff --git a/docs/library/micropython.rst b/docs/library/micropython.rst
index 4ff0b0c15..c13a7391b 100644
--- a/docs/library/micropython.rst
+++ b/docs/library/micropython.rst
@@ -46,7 +46,7 @@ Functions
 
 .. function:: mem_info([verbose])
 
-   Print information about currently used memory.  If the *verbose`* argument
+   Print information about currently used memory.  If the *verbose* argument
    is given then extra information is printed.
 
    The information that is printed is implementation dependent, but currently
diff --git a/docs/library/network.rst b/docs/library/network.rst
index de93c0e01..def6bee74 100644
--- a/docs/library/network.rst
+++ b/docs/library/network.rst
@@ -9,7 +9,7 @@ This module provides network drivers and routing configuration. To use this
 module, a MicroPython variant/build with network capabilities must be installed.
 Network drivers for specific hardware are available within this module and are
 used to configure hardware network interface(s). Network services provided
-by configured interfaces are then available for use via the :mod:`socket`
+by configured interfaces are then available for use via the :mod:`usocket`
 module.
 
 For example::
@@ -39,9 +39,9 @@ Common network adapter interface
 ================================
 
 This section describes an (implied) abstract base class for all network
-interface classes implemented by different ports of MicroPython for
-different hardware. This means that MicroPython does not actually
-provide `AbstractNIC` class, but any actual NIC class, as described
+interface classes implemented by `MicroPython ports <MicroPython port>`
+for different hardware. This means that MicroPython does not actually
+provide ``AbstractNIC`` class, but any actual NIC class, as described
 in the following sections, implements methods as described here.
 
 .. class:: AbstractNIC(id=None, ...)
@@ -411,7 +411,7 @@ parameter should be `id`.
         print(ap.config('channel'))
 
        Following are commonly supported parameters (availability of a specific parameter
-       depends on network technology type, driver, and MicroPython port).
+       depends on network technology type, driver, and `MicroPython port`).
 
        =========  ===========
        Parameter  Description
diff --git a/docs/library/uos.rst b/docs/library/uos.rst
index 7c52c1eea..43bf69cc0 100644
--- a/docs/library/uos.rst
+++ b/docs/library/uos.rst
@@ -89,8 +89,22 @@ Functions
    Return a bytes object with n random bytes. Whenever possible, it is
    generated by the hardware random number generator.
 
-.. function:: dupterm(stream_object)
+.. function:: dupterm(stream_object, index=0)
 
-   Duplicate or switch MicroPython terminal (the REPL) on the passed stream-like
-   object. The given object must implement the ``readinto()`` and ``write()``
-   methods. If ``None`` is passed, previously set redirection is cancelled.
+   Duplicate or switch the MicroPython terminal (the REPL) on the given stream-like
+   object. The *stream_object* argument must implement the ``readinto()`` and
+   ``write()`` methods.  The stream should be in non-blocking mode and
+   ``readinto()`` should return ``None`` if there is no data available for reading.
+
+   After calling this function all terminal output is repeated on this stream,
+   and any input that is available on the stream is passed on to the terminal input.
+
+   The *index* parameter should be a non-negative integer and specifies which
+   duplication slot is set.  A given port may implement more than one slot (slot 0
+   will always be available) and in that case terminal input and output is
+   duplicated on all the slots that are set.
+
+   If ``None`` is passed as the *stream_object* then duplication is cancelled on
+   the slot given by *index*.
+
+   The function returns the previous stream-like object in the given slot.
diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst
index 65e24e266..dfdcd68bc 100644
--- a/docs/library/usocket.rst
+++ b/docs/library/usocket.rst
@@ -117,12 +117,12 @@ Constants
 .. data:: usocket.SOL_*
 
    Socket option levels (an argument to `setsockopt()`). The exact
-   inventory depends on a MicroPython port.
+   inventory depends on a `MicroPython port`.
 
 .. data:: usocket.SO_*
 
    Socket options (an argument to `setsockopt()`). The exact
-   inventory depends on a MicroPython port.
+   inventory depends on a `MicroPython port`.
 
 Constants specific to WiPy:
 
diff --git a/docs/pyboard/tutorial/pass_through.rst b/docs/pyboard/tutorial/pass_through.rst
index a94e7363d..012a90764 100644
--- a/docs/pyboard/tutorial/pass_through.rst
+++ b/docs/pyboard/tutorial/pass_through.rst
@@ -15,4 +15,4 @@ It's as simple as::
             if uart.any():
                 usb.write(uart.read(256))
 
-    pass_through(pyb.USB_VCP(), pyb.UART(1, 9600))
+    pass_through(pyb.USB_VCP(), pyb.UART(1, 9600, timeout=0))
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 98979afa9..4cd3d84cc 100644
--- a/docs/reference/glossary.rst
+++ b/docs/reference/glossary.rst
@@ -56,9 +56,9 @@ Glossary
         which provides implementations for many modules from CPython's
         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 is 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
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
 ----------