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

9 files changed, 116 insertions, 94 deletions

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.