ports/nrf: Upmerging port with upstream master

17 files changed, 187 insertions, 57 deletions

diff --git a/docs/conf.py b/docs/conf.py
index 2c3423d99..a8df37315 100755
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -98,7 +98,7 @@ copyright = '2014-2017, Damien P. George, Paul Sokolovsky, and contributors'
 #
 # We don't follow "The short X.Y version" vs "The full version, including alpha/beta/rc tags"
 # breakdown, so use the same version identifier for both to avoid confusion.
-version = release = '1.9.1'
+version = release = '1.9.2'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
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/index.rst b/docs/library/index.rst
index e884f266e..0789ea43d 100644
--- a/docs/library/index.rst
+++ b/docs/library/index.rst
@@ -40,8 +40,7 @@ information pertaining to a specific port.
 
 Beyond the built-in libraries described in this documentation, many more
 modules from the Python standard library, as well as further MicroPython
-extensions to it, can be found in the `micropython-lib repository
-<https://github.com/micropython/micropython-lib>`_.
+extensions to it, can be found in `micropython-lib`.
 
 Python standard libraries and micro-libraries
 ---------------------------------------------
@@ -54,7 +53,7 @@ e.g. ``ujson`` instead of ``json``. This is to signify that such a module is
 micro-library, i.e. implements only a subset of CPython module functionality.
 By naming them differently, a user has a choice to write a Python-level module
 to extend functionality for better compatibility with CPython (indeed, this is
-what done by micropython-lib project mentioned above).
+what done by the `micropython-lib` project mentioned above).
 
 On some embedded platforms, where it may be cumbersome to add Python-level
 wrapper modules to achieve naming compatibility with CPython, micro-modules
diff --git a/docs/library/machine.RTC.rst b/docs/library/machine.RTC.rst
index 2a53b9146..95fa2b4ce 100644
--- a/docs/library/machine.RTC.rst
+++ b/docs/library/machine.RTC.rst
@@ -38,7 +38,7 @@ Methods
 
    Resets the RTC to the time of January 1, 2015 and starts running it again.
 
-.. method:: RTC.alarm(id, time, /*, repeat=False)
+.. method:: RTC.alarm(id, time, \*, repeat=False)
 
    Set the RTC alarm. Time might be either a millisecond value to program the alarm to
    current time + time_in_ms in the future, or a datetimetuple. If the time passed is in
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/sys.rst b/docs/library/sys.rst
index 0bec35cc9..d49577306 100644
--- a/docs/library/sys.rst
+++ b/docs/library/sys.rst
@@ -28,7 +28,7 @@ Functions
       this function takes just exception value instead of exception type,
       exception value, and traceback object; *file* argument should be
       positional; further arguments are not supported. CPython-compatible
-      ``traceback`` module can be found in micropython-lib.
+      ``traceback`` module can be found in `micropython-lib`.
 
 Constants
 ---------
diff --git a/docs/library/ubinascii.rst b/docs/library/ubinascii.rst
index 0664d5b09..192d34514 100644
--- a/docs/library/ubinascii.rst
+++ b/docs/library/ubinascii.rst
@@ -29,8 +29,12 @@ Functions
 
 .. function:: a2b_base64(data)
 
-   Convert Base64-encoded data to binary representation. Returns bytes string.
+   Decode base64-encoded data, ignoring invalid characters in the input.
+   Conforms to `RFC 2045 s.6.8 <https://tools.ietf.org/html/rfc2045#section-6.8>`_.
+   Returns a bytes object.
 
 .. function:: b2a_base64(data)
 
-   Encode binary data in Base64 format. Returns string.
+   Encode binary data in base64 format, as in `RFC 3548
+   <https://tools.ietf.org/html/rfc3548.html>`_. Returns the encoded data
+   followed by a newline character, as a bytes object.
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 70d4f49fc..dfdcd68bc 100644
--- a/docs/library/usocket.rst
+++ b/docs/library/usocket.rst
@@ -12,12 +12,6 @@ This module provides access to the BSD socket interface.
 .. admonition:: Difference to CPython
    :class: attention
 
-   CPython used to have a ``socket.error`` exception which is now deprecated,
-   and is an alias of `OSError`. In MicroPython, use `OSError` directly.
-
-.. admonition:: Difference to CPython
-   :class: attention
-
    For efficiency and consistency, socket objects in MicroPython implement a stream
    (file-like) interface directly. In CPython, you need to convert a socket to
    a file-like object using `makefile()` method. This method is still supported
@@ -27,11 +21,47 @@ This module provides access to the BSD socket interface.
 Socket address format(s)
 ------------------------
 
-The functions below which expect a network address, accept it in the format of
-*(ipv4_address, port)*, where *ipv4_address* is a string with dot-notation numeric
-IPv4 address, e.g. ``"8.8.8.8"``, and port is integer port number in the range
-1-65535. Note the domain names are not accepted as *ipv4_address*, they should be
-resolved first using `usocket.getaddrinfo()`.
+The native socket address format of the ``usocket`` module is an opaque data type
+returned by `getaddrinfo` function, which must be used to resolve textual address
+(including numeric addresses)::
+
+    sockaddr = usocket.getaddrinfo('www.micropython.org', 80)[0][-1]
+    # You must use getaddrinfo() even for numeric addresses
+    sockaddr = usocket.getaddrinfo('127.0.0.1', 80)[0][-1]
+    # Now you can use that address
+    sock.connect(addr)
+
+Using `getaddrinfo` is the most efficient (both in terms of memory and processing
+power) and portable way to work with addresses.
+
+However, ``socket`` module (note the difference with native MicroPython
+``usocket`` module described here) provides CPython-compatible way to specify
+addresses using tuples, as described below. Note that depending on a
+`MicroPython port`, ``socket`` module can be builtin or need to be
+installed from `micropython-lib` (as in the case of `MicroPython Unix port`),
+and some ports still accept only numeric addresses in the tuple format,
+and require to use `getaddrinfo` function to resolve domain names.
+
+Summing up:
+
+* Always use `getaddrinfo` when writing portable applications.
+* Tuple addresses described below can be used as a shortcut for
+  quick hacks and interactive use, if your port supports them.
+
+Tuple address format for ``socket`` module:
+
+* IPv4: *(ipv4_address, port)*, where *ipv4_address* is a string with
+  dot-notation numeric IPv4 address, e.g. ``"8.8.8.8"``, and *port* is and
+  integer port number in the range 1-65535. Note the domain names are not
+  accepted as *ipv4_address*, they should be resolved first using
+  `usocket.getaddrinfo()`.
+* IPv6: *(ipv6_address, port, flowinfo, scopeid)*, where *ipv6_address*
+  is a string with colon-notation numeric IPv6 address, e.g. ``"2001:db8::1"``,
+  and *port* is an integer port number in the range 1-65535. *flowinfo*
+  must be 0. *scopeid* is the interface scope identifier for link-local
+  addresses. Note the domain names are not accepted as *ipv6_address*,
+  they should be resolved first using `usocket.getaddrinfo()`. Availability
+  of IPv6 support depends on a `MicroPython port`.
 
 Functions
 ---------
@@ -87,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:
 
@@ -250,3 +280,13 @@ Methods
    the length of *buf*.
 
    Return value: number of bytes written.
+
+.. exception:: socket.error
+
+   MicroPython does NOT have this exception.
+
+   .. admonition:: Difference to CPython
+        :class: attention
+
+        CPython used to have a ``socket.error`` exception which is now deprecated,
+        and is an alias of `OSError`. In MicroPython, use `OSError` directly.
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 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
 ----------