Merge tag 'v1.9.1' into parse-bytecode

Fixes for stmhal USB mass storage, lwIP bindings and VFS regressions

This release provides an important fix for the USB mass storage device in
the stmhal port by implementing the SCSI SYNCHRONIZE_CACHE command, which
is now require by some Operating Systems.  There are also fixes for the
lwIP bindings to improve non-blocking sockets and error codes.  The VFS has
some regressions fixed including the ability to statvfs the root.

All changes are listed below.

py core:
- modbuiltins: add core-provided version of input() function
- objstr: catch case of negative "maxsplit" arg to str.rsplit()
- persistentcode: allow to compile with complex numbers disabled
- objstr: allow to compile with obj-repr D, and unicode disabled
- modsys: allow to compile with obj-repr D and PY_ATTRTUPLE disabled
- provide mp_decode_uint_skip() to help reduce stack usage
- makeqstrdefs.py: make script run correctly with Python 2.6
- objstringio: if created from immutable object, follow copy on write policy

extmod:
- modlwip: connect: for non-blocking mode, return EINPROGRESS
- modlwip: fix error codes for duplicate calls to connect()
- modlwip: accept: fix error code for non-blocking mode
- vfs: allow to statvfs the root directory
- vfs: allow "buffering" and "encoding" args to VFS's open()
- modframebuf: fix signed/unsigned comparison pendantic warning

lib:
- libm: use isfinite instead of finitef, for C99 compatibility
- utils/interrupt_char: remove support for KBD_EXCEPTION disabled

tests:
- basics/string_rsplit: add tests for negative "maxsplit" argument
- float: convert "sys.exit()" to "raise SystemExit"
- float/builtin_float_minmax: PEP8 fixes
- basics: convert "sys.exit()" to "raise SystemExit"
- convert remaining "sys.exit()" to "raise SystemExit"

unix port:
- convert to use core-provided version of built-in import()
- Makefile: replace references to make with $(MAKE)

windows port:
- convert to use core-provided version of built-in import()

qemu-arm port:
- Makefile: adjust object-file lists to get correct dependencies
- enable micropython.mem_*() functions to allow more tests

stmhal port:
- boards: enable DAC for NUCLEO_F767ZI board
- add support for NUCLEO_F446RE board
- pass USB handler as parameter to allow more than one USB handler
- usb: use local USB handler variable in Start-of-Frame handler
- usb: make state for USB device private to top-level USB driver
- usbdev: for MSC implement SCSI SYNCHRONIZE_CACHE command
- convert from using stmhal's input() to core provided version

cc3200 port:
- convert from using stmhal's input() to core provided version

teensy port:
- convert from using stmhal's input() to core provided version

esp8266 port:
- Makefile: replace references to make with $(MAKE)
- Makefile: add clean-modules target
- convert from using stmhal's input() to core provided version

zephyr port:
- modusocket: getaddrinfo: Fix mp_obj_len() usage
- define MICROPY_PY_SYS_PLATFORM (to "zephyr")
- machine_pin: use native Zephyr types for Zephyr API calls

docs:
- machine.Pin: remove out_value() method
- machine.Pin: add on() and off() methods
- esp8266: consistently replace Pin.high/low methods with .on/off
- esp8266/quickref: polish Pin.on()/off() examples
- network: move confusingly-named cc3200 Server class to its reference
- uos: deconditionalize, remove minor port-specific details
- uos: move cc3200 port legacy VFS mounting functions to its ref doc
- machine: sort machine classes in logical order, not alphabetically
- network: first step to describe standard network class interface

examples:
- embedding: use core-provided KeyboardInterrupt object

17 files changed, 193 insertions, 108 deletions

diff --git a/docs/conf.py b/docs/conf.py
index e813f23836..8fb53e890c 100755
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -99,7 +99,7 @@ copyright = '2014-2017, Damien P. George, Paul Sokolovsky, and contributors'
 # The short X.Y version.
 version = '1.9'
 # The full version, including alpha/beta/rc tags.
-release = '1.9'
+release = '1.9.1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/docs/esp8266/quickref.rst b/docs/esp8266/quickref.rst
index 5ff33e02bd..ccf6365c83 100644
--- a/docs/esp8266/quickref.rst
+++ b/docs/esp8266/quickref.rst
@@ -107,9 +107,9 @@ Use the :ref:`machine.Pin <machine.Pin>` class::
     from machine import Pin
 
     p0 = Pin(0, Pin.OUT)    # create output pin on GPIO0
-    p0.high()               # set pin to high
-    p0.low()                # set pin to low
-    p0.value(1)             # set pin to high
+    p0.on()                 # set pin to "on" (high) level
+    p0.off()                # set pin to "off" (low) level
+    p0.value(1)             # set pin to on/high
 
     p2 = Pin(2, Pin.IN)     # create input pin on GPIO2
     print(p2.value())       # get value, 0 or 1
diff --git a/docs/esp8266/tutorial/pins.rst b/docs/esp8266/tutorial/pins.rst
index a44f40d3a7..cd45c83cd3 100644
--- a/docs/esp8266/tutorial/pins.rst
+++ b/docs/esp8266/tutorial/pins.rst
@@ -35,8 +35,8 @@ Then set its value using::
 
 Or::
 
-    >>> pin.low()
-    >>> pin.high()
+    >>> pin.off()
+    >>> pin.on()
 
 External interrupts
 -------------------
diff --git a/docs/esp8266/tutorial/repl.rst b/docs/esp8266/tutorial/repl.rst
index 21e889c9a8..ba64fcccbe 100644
--- a/docs/esp8266/tutorial/repl.rst
+++ b/docs/esp8266/tutorial/repl.rst
@@ -101,11 +101,12 @@ turn it on and off using the following code::
 
     >>> import machine
     >>> pin = machine.Pin(2, machine.Pin.OUT)
-    >>> pin.high()
-    >>> pin.low()
+    >>> pin.on()
+    >>> pin.off()
 
-Note that ``high`` might turn the LED off and ``low`` might turn it on (or vice
-versa), depending on how the LED is wired on your board.
+Note that ``on`` method of a Pin might turn the LED off and ``off`` might
+turn it on (or vice versa), depending on how the LED is wired on your board.
+To resolve this, machine.Signal class is provided.
 
 Line editing
 ~~~~~~~~~~~~
diff --git a/docs/library/btree.rst b/docs/library/btree.rst
index aebcbc1604..bd7890586a 100644
--- a/docs/library/btree.rst
+++ b/docs/library/btree.rst
@@ -69,7 +69,7 @@ Functions
 
    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
-   paramters of the database operation (most users will not need them):
+   parameters of the database operation (most users will not need them):
 
    * `flags` - Currently unused.
    * `cachesize` - Suggested maximum memory cache size in bytes. For a
diff --git a/docs/library/machine.Pin.rst b/docs/library/machine.Pin.rst
index 2efd84688a..05ceb4ad33 100644
--- a/docs/library/machine.Pin.rst
+++ b/docs/library/machine.Pin.rst
@@ -146,18 +146,20 @@ Methods
 
    When setting the value this method returns ``None``.
 
-.. method:: Pin.out_value()
-
-   Return the value stored in the output buffer of a pin, regardless of its mode.
-
-   Not all ports implement this method.
-
 .. method:: Pin.__call__([x])
 
    Pin objects are callable.  The call method provides a (fast) shortcut to set
    and get the value of the pin.  It is equivalent to Pin.value([x]).
    See :meth:`Pin.value` for more details.
 
+.. method:: Pin.on()
+
+   Set pin to "1" output level.
+
+.. method:: Pin.off()
+
+   Set pin to "0" output level.
+
 .. method:: Pin.mode([mode])
 
    Get or set the pin mode.
diff --git a/docs/library/machine.SD.rst b/docs/library/machine.SD.rst
index 0eb024602f..608e958317 100644
--- a/docs/library/machine.SD.rst
+++ b/docs/library/machine.SD.rst
@@ -34,7 +34,7 @@ Methods
 
 .. method:: SD.init(id=0, pins=('GP10', 'GP11', 'GP15'))
 
-   Enable the SD card. In order to initalize the card, give it a 3-tuple:
+   Enable the SD card. In order to initialize the card, give it a 3-tuple:
    ``(clk_pin, cmd_pin, dat0_pin)``.
 
 .. method:: SD.deinit()
diff --git a/docs/library/machine.UART.rst b/docs/library/machine.UART.rst
index f9c8efef78..64ff28e1ab 100644
--- a/docs/library/machine.UART.rst
+++ b/docs/library/machine.UART.rst
@@ -16,7 +16,7 @@ UART objects can be created and initialised using::
     uart = UART(1, 9600)                         # init with given baudrate
     uart.init(9600, bits=8, parity=None, stop=1) # init with given parameters
 
-Supported paramters differ on a board:
+Supported parameters differ on a board:
 
 Pyboard: Bits can be 7, 8 or 9. Stop can be 1 or 2. With `parity=None`,
 only 8 and 9 bits are supported.  With parity enabled, only 7 and 8 bits
diff --git a/docs/library/machine.rst b/docs/library/machine.rst
index c2c6b83fd6..7ea7f565e7 100644
--- a/docs/library/machine.rst
+++ b/docs/library/machine.rst
@@ -145,13 +145,13 @@ Classes
  .. toctree::
    :maxdepth: 1
 
-   machine.I2C.rst
    machine.Pin.rst
    machine.Signal.rst
-   machine.RTC.rst
+   machine.UART.rst
    machine.SPI.rst
+   machine.I2C.rst
+   machine.RTC.rst
    machine.Timer.rst
-   machine.UART.rst
    machine.WDT.rst
 
 .. only:: port_wipy
@@ -159,12 +159,12 @@ Classes
  .. toctree::
    :maxdepth: 1
 
-   machine.ADC.rst
-   machine.I2C.rst
    machine.Pin.rst
-   machine.RTC.rst
-   machine.SD.rst
+   machine.UART.rst
    machine.SPI.rst
+   machine.I2C.rst
+   machine.RTC.rst
    machine.Timer.rst
-   machine.UART.rst
    machine.WDT.rst
+   machine.ADC.rst
+   machine.SD.rst
diff --git a/docs/library/network.rst b/docs/library/network.rst
index 251e68c76e..27fa0dcb2f 100644
--- a/docs/library/network.rst
+++ b/docs/library/network.rst
@@ -14,14 +14,20 @@ module.
 
 For example::
 
-    # configure a specific network interface
+    # connect/ show IP config a specific network interface
     # see below for examples of specific drivers
     import network
+    import utime
     nic = network.Driver(...)
+    if not nic.isconnected():
+        nic.connect()
+        print("Waiting for connection...")
+        while not nic.isconnected():
+            utime.sleep(1)
     print(nic.ifconfig())
 
-    # now use socket as usual
-    import socket
+    # now use usocket as usual
+    import usocket as socket
     addr = socket.getaddrinfo('micropython.org', 80)[0][-1]
     s = socket.socket()
     s.connect(addr)
@@ -29,51 +35,102 @@ For example::
     data = s.recv(1000)
     s.close()
 
-.. only:: port_wipy
+Common network adapter interface
+================================
 
-    .. _network.Server:
+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
+in the following sections, implements methods as described here.
 
-    class Server
-    ============
+.. class:: AbstractNIC(id=None, ...)
 
-    The ``Server`` class controls the behaviour and the configuration of the FTP and telnet
-    services running on the WiPy. Any changes performed using this class' methods will
-    affect both.
+Instantiate a network interface object. Parameters are network interface
+dependent. If there are more than one interface of the same type, the first
+parameter should be `id`.
 
-    Example::
+    .. method:: active([is_active])
 
-        import network
-        server = network.Server()
-        server.deinit() # disable the server
-        # enable the server again with new settings
-        server.init(login=('user', 'password'), timeout=600)
+        Activate ("up") or deactivate ("down") the network interface, if
+        a boolean argument is passed. Otherwise, query current state if
+        no argument is provided. Most other methods require an active
+        interface (behavior of calling them on inactive interface is
+        undefined).
 
-    Constructors
-    ------------
+    .. method:: connect([service_id, key=None, \*, ...])
 
-    .. class:: network.Server(id, ...)
+       Connect the interface to a network. This method is optional, and
+       available only for interfaces which are not "always connected".
+       If no parameters are given, connect to the default (or the only)
+       service. If a single parameter is given, it is the primary identifier
+       of a service to connect to. It may be accompanied by a key
+       (password) required to access said service. There can be further
+       arbitrary keyword-only parameters, depending on the networking medium
+       type and/or particular device. Parameters can be used to: a)
+       specify alternative service identifer types; b) provide additional
+       connection parameters. For various medium types, there are different
+       sets of predefined/recommended parameters, among them:
 
-       Create a server instance, see ``init`` for parameters of initialization.
+       * WiFi: `bssid` keyword to connect by BSSID (MAC address) instead
+         of access point name
 
-    Methods
-    -------
+    .. method:: disconnect()
+
+       Disconnect from network.
+
+    .. method:: isconnected()
+
+       Returns ``True`` if connected to network, otherwise returns ``False``.
+
+    .. method:: scan(\*, ...)
+
+       Scan for the available network services/connections. Returns a
+       list of tuples with discovered service parameters. For various
+       network media, there are different variants of predefined/
+       recommended tuple formats, among them:
+
+       * WiFi: (ssid, bssid, channel, RSSI, authmode, hidden). There
+         may be further fields, specific to a particular device.
 
-    .. method:: server.init(\*, login=('micro', 'python'), timeout=300)
+       The function may accept additional keyword arguments to filter scan
+       results (e.g. scan for a particular service, on a particular channel,
+       for services of a particular set, etc.), and to affect scan
+       duration and other parameters. Where possible, parameter names
+       should match those in connect().
 
-       Init (and effectively start the server). Optionally a new ``user``, ``password``
-       and ``timeout`` (in seconds) can be passed.
+    .. method:: status()
 
-    .. method:: server.deinit()
+       Return detailed status of the interface, values are dependent
+       on the network medium/technology.
 
-       Stop the server
+    .. method:: ifconfig([(ip, subnet, gateway, dns)])
 
-    .. method:: server.timeout([timeout_in_seconds])
+       Get/set IP-level network interface parameters: IP address, subnet mask,
+       gateway and DNS server. When called with no arguments, this method returns
+       a 4-tuple with the above information. To set the above values, pass a
+       4-tuple with the required information.  For example::
 
-       Get or set the server timeout.
+        nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8'))
 
-    .. method:: server.isrunning()
+    .. method:: config('param')
+                config(param=value, ...)
 
-       Returns ``True`` if the server is running, ``False`` otherwise.
+       Get or set general network interface parameters. These methods allow to work
+       with additional parameters beyond standard IP configuration (as dealt with by
+       ``ifconfig()``). These include network-specific and hardware-specific
+       parameters and status values. For setting parameters, the keyword argument
+       syntax should be used, and multiple parameters can be set at once. For
+       querying, a parameter name should be quoted as a string, and only one
+       parameter can be queried at a time::
+
+        # Set WiFi access point name (formally known as ESSID) and WiFi channel
+        ap.config(essid='My AP', channel=11)
+        # Query params one by one
+        print(ap.config('essid'))
+        print(ap.config('channel'))
+        # Extended status information also available this way
+        print(sta.config('rssi'))
 
 .. only:: port_pyboard
 
diff --git a/docs/library/uhashlib.rst b/docs/library/uhashlib.rst
index cd0216dae9..6b9a764ba8 100644
--- a/docs/library/uhashlib.rst
+++ b/docs/library/uhashlib.rst
@@ -15,11 +15,11 @@ be implemented:
 
 * SHA1 - A previous generation algorithm. Not recommended for new usages,
   but SHA1 is a part of number of Internet standards and existing
-  applications, so boards targetting network connectivity and
+  applications, so boards targeting network connectivity and
   interoperatiability will try to provide this.
 
 * MD5 - A legacy algorithm, not considered cryptographically secure. Only
-  selected boards, targetting interoperatibility with legacy applications,
+  selected boards, targeting interoperatibility with legacy applications,
   will offer this.
 
 Constructors
diff --git a/docs/library/uos.rst b/docs/library/uos.rst
index d1f83d2cc3..3d0aa46c70 100644
--- a/docs/library/uos.rst
+++ b/docs/library/uos.rst
@@ -4,28 +4,9 @@
 .. module:: uos
    :synopsis: basic "operating system" services
 
-The ``os`` module contains functions for filesystem access and ``urandom``
+The ``uos`` module contains functions for filesystem access and ``urandom``
 function.
 
-Port specifics
---------------
-
-The filesystem has ``/`` as the root directory and the
-available physical drives are accessible from here.  They are currently:
-
-    ``/flash``      -- the internal flash filesystem
-
-    ``/sd``         -- the SD card (if it exists)
-
-.. only:: port_pyboard
-
-    On boot up, the current directory is ``/flash`` if no SD card is inserted,
-    otherwise it is ``/sd``.
-
-.. only:: port_wipy
-
-    On boot up, the current directory is ``/flash``.
-
 Functions
 ---------
 
@@ -106,26 +87,8 @@ Functions
    Return a bytes object with n random bytes. Whenever possible, it is
    generated by the hardware random number generator.
 
-.. only:: port_wipy
-
-    .. function:: mount(block_device, mount_point, \*, readonly=False)
-
-       Mounts a block device (like an ``SD`` object) in the specified mount
-       point. Example::
-
-          os.mount(sd, '/sd')
-
-    .. function:: unmount(path)
-
-       Unmounts a previously mounted block device from the given path.
-
-    .. function:: mkfs(block_device or path)
-
-       Formats the specified path, must be either ``/flash`` or ``/sd``.
-       A block device can also be passed like an ``SD`` object before
-       being mounted.
-
-    .. function:: dupterm(stream_object)
+.. function:: dupterm(stream_object)
 
-       Duplicate the terminal (the REPL) on the passed stream-like object.
-       The given object must at least implement the ``.read()`` and ``.write()`` methods.
+   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.
diff --git a/docs/library/utime.rst b/docs/library/utime.rst
index 871f6c678d..f3a067cdef 100644
--- a/docs/library/utime.rst
+++ b/docs/library/utime.rst
@@ -146,8 +146,8 @@ Functions
    too distant inbetween, see below). The function returns **signed** value in the range
    [``-TICKS_PERIOD/2`` .. ``TICKS_PERIOD/2-1``] (that's a typical range definition for
    two's-complement signed binary integers). If the result is negative, it means that
-   ``ticks1`` occured earlier in time than ``ticks2``. Otherwise, it means that
-   ``ticks1`` occured after ``ticks2``. This holds ``only`` if ``ticks1`` and ``ticks2``
+   ``ticks1`` occurred earlier in time than ``ticks2``. Otherwise, it means that
+   ``ticks1`` occurred after ``ticks2``. This holds ``only`` if ``ticks1`` and ``ticks2``
    are apart from each other for no more than ``TICKS_PERIOD/2-1`` ticks. If that does
    not hold, incorrect result will be returned. Specifically, if two tick values are
    apart for ``TICKS_PERIOD/2-1`` ticks, that value will be returned by the function.
diff --git a/docs/pyboard/general.rst b/docs/pyboard/general.rst
index 48e0146442..1d040f6ccc 100644
--- a/docs/pyboard/general.rst
+++ b/docs/pyboard/general.rst
@@ -10,7 +10,9 @@ is inserted into the slot, it is available as ``/sd``.
 
 When the pyboard boots up, it needs to choose a filesystem to boot from.  If
 there is no SD card, then it uses the internal filesystem ``/flash`` as the boot
-filesystem, otherwise, it uses the SD card ``/sd``.
+filesystem, otherwise, it uses the SD card ``/sd``. After the boot, the current
+directory is set to one of the directories above.
+
 If needed, you can prevent the use of the SD card by creating an empty file
 called ``/flash/SKIPSD``.  If this file exists when the pyboard boots
 up then the SD card will be skipped and the pyboard will always boot from the
diff --git a/docs/sphinx_selective_exclude/README.md b/docs/sphinx_selective_exclude/README.md
index cc9725c21c..dab1407392 100644
--- a/docs/sphinx_selective_exclude/README.md
+++ b/docs/sphinx_selective_exclude/README.md
@@ -66,7 +66,7 @@ index for PDF, just the same as for HTML.
 search_auto_exclude
 -------------------
 
-Even if you exclude soem documents from toctree:: using only::
+Even if you exclude some documents from toctree:: using only::
 directive, they will be indexed for full-text search, so user may
 find them and get confused. This plugin follows very simple idea
 that if you didn't include some documents in the toctree, then
diff --git a/docs/sphinx_selective_exclude/modindex_exclude.py b/docs/sphinx_selective_exclude/modindex_exclude.py
index 18b49cc80f..bf8db795e6 100644
--- a/docs/sphinx_selective_exclude/modindex_exclude.py
+++ b/docs/sphinx_selective_exclude/modindex_exclude.py
@@ -2,7 +2,7 @@
 # This is a Sphinx documentation tool extension which allows to
 # exclude some Python modules from the generated indexes. Modules
 # are excluded both from "modindex" and "genindex" index tables
-# (in the latter case, all members of a module are exlcuded).
+# (in the latter case, all members of a module are excluded).
 # To control exclusion, set "modindex_exclude" variable in Sphinx
 # conf.py to the list of modules to exclude. Note: these should be
 # modules (as defined by py:module directive, not just raw filenames).
diff --git a/docs/wipy/general.rst b/docs/wipy/general.rst
index 8b9b91c534..f28edb4e4b 100644
--- a/docs/wipy/general.rst
+++ b/docs/wipy/general.rst
@@ -53,7 +53,7 @@ which is stored within the external serial flash memory.  If a micro SD card
 is hooked-up and mounted, it will be available as well.
 
 When the WiPy starts up, it always boots from the ``boot.py`` located in the
-``/flash`` file system.
+``/flash`` file system. On boot up, the current directory is ``/flash``.
 
 The file system is accessible via the native FTP server running in the WiPy.
 Open your FTP client of choice and connect to:
@@ -323,3 +323,63 @@ Unrelated function in machine module
     this function is not called then the default file main.py will be executed.
 
     It only makes sense to call this function from within boot.py.
+
+Adhoc way to control telnet/FTP server via network module
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``Server`` class controls the behaviour and the configuration of the FTP and telnet
+services running on the WiPy. Any changes performed using this class' methods will
+affect both.
+
+Example::
+
+    import network
+    server = network.Server()
+    server.deinit() # disable the server
+    # enable the server again with new settings
+    server.init(login=('user', 'password'), timeout=600)
+
+.. class:: network.Server(id, ...)
+
+   Create a server instance, see ``init`` for parameters of initialization.
+
+.. method:: server.init(\*, login=('micro', 'python'), timeout=300)
+
+   Init (and effectively start the server). Optionally a new ``user``, ``password``
+   and ``timeout`` (in seconds) can be passed.
+
+.. method:: server.deinit()
+
+   Stop the server
+
+.. method:: server.timeout([timeout_in_seconds])
+
+   Get or set the server timeout.
+
+.. method:: server.isrunning()
+
+   Returns ``True`` if the server is running, ``False`` otherwise.
+
+Adhoc VFS-like support
+~~~~~~~~~~~~~~~~~~~~~~
+
+WiPy doesn't implement full MicroPython VFS support, instead following
+functions are defined in ``uos`` module:
+
+.. function:: mount(block_device, mount_point, \*, readonly=False)
+
+   Mounts a block device (like an ``SD`` object) in the specified mount
+   point. Example::
+
+      os.mount(sd, '/sd')
+
+.. function:: unmount(path)
+
+   Unmounts a previously mounted block device from the given path.
+
+.. function:: mkfs(block_device or path)
+
+   Formats the specified path, must be either ``/flash`` or ``/sd``.
+   A block device can also be passed like an ``SD`` object before
+   being mounted.
+