Merge tag 'v1.8.6' into parse-bytecode

ESP8266 port uses SDK 2.0, has more heap, has support for 512k devices

This release brings some code size reductions to the core as well as
more tests and improved coverage which is now at 94.3%.

The time.ticks_diff(a, b) function has changed: the order of the arguments
has been swapped so that it behaves like "a - b", and it can now return a
negative number if "a" came before "b" (modulo the period of the ticks
functions).

For the ESP8266 port the Espressif SDK has been updated to 2.0.0, the
heap has been increased from 28k to 36k, and there is support for 512k
devices via "make 512k".  upip is included by default as frozen bytecode.
The network module now allows access-point reconnection without WiFi
credentials, and exposes configuration for the station DHCP hostname.  The
DS18B20 driver now handles negative temperatures, and NeoPixel and APA102
drivers handle 4 bytes-per-pixel LEDs.

For the CC3200 port there is now support for loading of precompiled .mpy
files and threading now works properly with interrupts.

A detailed list of changes follows.

py core:
- py.mk: automatically add frozen.c to source list if FROZEN_DIR is defined
- be more specific with MP_DECLARE_CONST_FUN_OBJ macros
- specialise builtin funcs to use separate type for fixed arg count
- {modbuiltins,obj}: use MP_PYTHON_PRINTER where possible
- modbuiltins: add builtin "slice", pointing to existing slice type
- add "delattr" builtin, conditional on MICROPY_CPYTHON_COMPAT
- sequence: fix reverse slicing of lists
- fix null pointer dereference in mpz.c, fix missing va_end in warning.c
- remove asserts that are always true in emitbc.c
- fix wrong assumption that m_renew will not move if shrinking
- change config default so m_malloc0 uses memset if GC not enabled
- add MICROPY_FLOAT_CONST macro for defining float constants
- move frozen bytecode Makefile rules from ports to common mk files
- strip leading dirs from frozen mpy files, so any path can be used

extmod:
- vfs_fat_file: check fatfs f_sync() and f_close() returns for errors
- vfs_fat_file: make file.close() a no-op if file already closed
- utime_mphal: ticks_diff(): switch arg order, return signed value
- utime_mphal: add MP_THREAD_GIL_EXIT/ENTER warppers for sleep functions
- utime_mphal: implement ticks_add(), add to all maintained ports
- utime_mphal: allow ticks functions period be configurable by a port

lib:
- utils/pyhelp.c: use mp_printf() instead of printf()
- utils/pyexec: add mp_hal_set_interrupt_char() prototype
- libm: move Thumb-specific sqrtf function to separate file

drivers:
- add "from micropython import const" when const is used

tools:
- upgrade upip to 1.1.4: fix error on unix when installing to non-existing
  absolute path
- pip-micropython: remove deprecated wrapper tool
- check_code_size.sh: code size validation script for CI
- replace upip tarball with just source file, to make its inclusion as
  frozen modules in multiple ports less magic

tests:
- extmod/vfs_fat: improve VFS test coverage
- basics/builtin_slice: add test for "slice" builtin name
- basics: add test for builtin "delattr"
- extmod/vfs_fat_fsusermount: improve fsusermount test coverage
- extmod/vfs_fat_oldproto: test old block device protocol
- basics/gc1: garbage collector threshold() coverage
- extmod/uhashlib_sha1: coverage for SHA1 algorithm
- extmod/uhashlib_sha256: rename sha256.py test
- btree1: fix out of memory error running on esp8266
- extmod/ticks_diff: test for new semantics of ticks_diff()
- extmod/framebuf1: test framebuffer pixel clear, and text function

minimal port:
- Makefile: split rule for firmware.bin generation

unix port:
- Makefile: remove references to deprecated pip-micropython
- modtime: use ticks_diff() implementation from extmod/utime_mphal.c
- mphalport.h: add warning of mp_hal_delay_ms() implementation
- modtime: switch ticks/sleep_ms/us() to utime_mphal
- fix symbol references for x86 Mac
- replace upip tarball with just source file

windows port:
- enable utime_mphal following unix, define mp_hal_ticks_*
- fix utime_mphal compilation for msvc
- implement mp_hal_ticks_cpu in terms of QueryPerformanceCounter

qemu-arm port:
- exclude ticks_diff test for qemu-arm port
- exclude extmod/vfs_fat_fileio.py test
- exclude new vfs_fat tests
- enable software floating point support, and float tests

stmhal port:
- modutime: refactor to use extmod's version of ticks_cpu
- refactor pin usage to use mp_hal_pin API
- led: refactor LED to use mp_hal_pin_output() init function
- Makefile: use standard rules for frozen module generation
- modutime: consistently convert to MP_ROM_QSTR/MP_ROM_PTR
- enable SD power save (disable CLK on idle)

cc3200 port:
- use mp_raise_XXX helper functions to reduce code size
- mods/pybspi: allow "write" arg of read/readinto to be positional
- enable loading of precompiled .mpy files
- fix thread mutex's so threading works with interrupts

teensy port:
- update to provide new mp_hal_pin_XXX functions following stmhal

esp8266 port:
- Makefile: use latest esptool.py flash size auto-detection
- esp_init_data: auto-initialize system params with vendor SDK 2.0.0
- esp8266.ld: move help.o to iROM
- esp8266.ld: move modmachine.o to iROM
- esp8266.ld: move main.o to iROM
- add MP_FASTCODE modifier to put a function to iRAM
- main: mark nlr_jump_fail() as MP_FASTCODE
- modules/webrepl: enforce only one concurrent WebREPL connection
- etshal.h: add few more ESP8266 vendor lib prototypes
- modesp: add flash_user_start() function
- add support for building firmware version for 512K modules
- scripts: make neopixel/apa102 handle 4bpp LEDs with common code
- modutime: consistently convert to MP_ROM_QSTR/MP_ROM_PTR
- modnetwork: config(): fix copy-paste error in setting "mac"
- scripts/port_diag: add descriptions for esf_buf types
- modnetwork.c: allows AP reconnection without WiFi credentials
- main: bump heap size to 36K
- etshal.h: add prototypes for SPIRead/SPIWrite/SPIEraseSector
- etshal.h: adjust size of MD5_CTX structure
- modules: fix negative temperature in ds18x20 driver
- rename "machine" module implementation to use contemporary naming
- rework webrepl_setup to run over wired REPL
- espneopixel.c: solve glitching LED issues with cpu at 80MHz
- include upip as a standard frozen bytecode module
- update docs for esptool 1.2.1/SDK 2.0 (--flash_size=detect)
- modnetwork.c: expose configuration for station DHCP hostname

zephyr port:
- implement utime module
- use board/SoC values for startup banner based on Zephyr config
- initial implementation of machine.Pin
- zephyr_getchar: update for recent Zephyr refactor of console hooks
- support time -> utime module "weaklink"
- README: update for the current featureset, add more info
- mpconfigport.h: move less important params to the bottom
- Makefile: allow to adjust heap size from make command line
- Makefile: update comments to the current state of affairs
- Makefile: allow to override Zephyr config from make command line
- Makefile: add minimal port
- Makefile: add -fomit-frame-pointer to reduce code size
- mphalport.h: update for new "unified" kernal API (sleep functions)

docs:
- machine.SPI: bring up to date with Hardware API, make vendor-neutral
- machine.SPI: improve descriptions of xfer methods
- library/builtins: add docs for delattr and slice
- library/network: reword intro paragraph
- library/network: typo fixes, consistent acronym capitalization
- library/index: update TOCs so builtins sorted before modules
- utime: document ticks_cpu() in more detail
- utime: describe new semantics of ticks_diff() (signed ring arithmetics)
- utime: add docs for ticks_add(), improvements for other ticks_*()
- esp8266: update for new WebREPL setup procedure
- */quickref.rst: use new semantics of ticks_diff()
- library/machine.Pin: update Pin docs to align with new HW API

travis:
- integrate tools/check_code_size.sh
- minimal: Use CROSS=1, for binary size check

examples:
- http_server_simplistic: add "not suitable for real use" note
- hwapi: example showing best practices for HW API usage in apps
- hwapi: add hwconfig for DragonBoard 410c

6 files changed, 391 insertions, 188 deletions

diff --git a/docs/library/builtins.rst b/docs/library/builtins.rst
index 42768ab99..d53c4d377 100644
--- a/docs/library/builtins.rst
+++ b/docs/library/builtins.rst
@@ -28,6 +28,11 @@ All builtin functions are described here. They are also available via
 
 .. class:: complex()
 
+.. function:: delattr(obj, name)
+
+   The argument *name* should be a string, and this function deletes the named
+   attribute from the object given by *obj*.
+
 .. class:: dict()
 
 .. function:: dir()
@@ -110,6 +115,10 @@ All builtin functions are described here. They are also available via
 
 .. function:: setattr()
 
+.. class:: slice()
+
+   The *slice* builtin is the type that slice objects have.
+
 .. function:: sorted()
 
 .. function:: staticmethod()
diff --git a/docs/library/index.rst b/docs/library/index.rst
index d502ffdfc..b06c806f7 100644
--- a/docs/library/index.rst
+++ b/docs/library/index.rst
@@ -51,8 +51,8 @@ library.
     .. toctree::
        :maxdepth: 1
 
-       array.rst
        builtins.rst
+       array.rst
        cmath.rst
        gc.rst
        math.rst
@@ -76,8 +76,8 @@ library.
     .. toctree::
        :maxdepth: 1
 
-       array.rst
        builtins.rst
+       array.rst
        cmath.rst
        gc.rst
        math.rst
@@ -101,8 +101,8 @@ library.
     .. toctree::
        :maxdepth: 1
 
-       array.rst
        builtins.rst
+       array.rst
        gc.rst
        select.rst
        sys.rst
@@ -119,8 +119,8 @@ library.
     .. toctree::
        :maxdepth: 1
 
-       array.rst
        builtins.rst
+       array.rst
        gc.rst
        math.rst
        sys.rst
diff --git a/docs/library/machine.Pin.rst b/docs/library/machine.Pin.rst
index db25787f9..952131f09 100644
--- a/docs/library/machine.Pin.rst
+++ b/docs/library/machine.Pin.rst
@@ -3,16 +3,44 @@
 class Pin -- control I/O pins
 =============================
 
-A pin is the basic object to control I/O pins (also known as GPIO -
-general-purpose input/output). It has methods to set
-the mode of the pin (input, output, etc) and methods to get and set the
-digital logic level. For analog control of a pin, see the ADC class.
+A pin object is used to control I/O pins (also known as GPIO - general-purpose
+input/output).  Pin objects are commonly associated with a physical pin that can
+drive an output voltage and read input voltages.  The pin class has methods to set the mode of
+the pin (IN, OUT, etc) and methods to get and set the digital logic level.
+For analog control of a pin, see the :class:`ADC` class.
 
-Usage Model:
+A pin object is constructed by using an identifier which unambiguously
+specifies a certain I/O pin.  The allowed forms of the identifier and the
+physical pin that the identifier maps to are port-specific.  Possibilities
+for the identifier are an integer, a string or a tuple with port and pin
+number.
+
+Usage Model::
+
+    from machine import Pin
+
+    # create an output pin on pin #0
+    p0 = Pin(0, Pin.OUT)
+
+    # set the value low then high
+    p0.value(0)
+    p0.value(1)
+
+    # create an input pin on pin #2, with a pull up resistor
+    p2 = Pin(2, Pin.IN, Pin.PULL_UP)
+
+    # read and print the pin value
+    print(p2.value())
+
+    # reconfigure pin #0 in input mode
+    p0.mode(p0.IN)
+
+    # configure an irq callback
+    p0.irq(lambda p:print(p))
 
 .. only:: port_wipy
 
-    Board pins are identified by their string id::
+    On the WiPy board the pins are identified by their string id::
 
         from machine import Pin
         g = machine.Pin('GP9', mode=Pin.OUT, pull=None, drive=Pin.MED_POWER, alt=-1)
@@ -40,174 +68,224 @@ Usage Model:
     All pin objects go through the pin mapper to come up with one of the
     gpio pins.
 
-.. only:: port_esp8266
+    For the ``drive`` parameter the strengths are:
 
-   ::
+      - ``Pin.LOW_POWER`` - 2mA drive capability.
+      - ``Pin.MED_POWER`` - 4mA drive capability.
+      - ``Pin.HIGH_POWER`` - 6mA drive capability.
 
-    from machine import Pin
+    For the ``alt`` parameter please refer to the pinout and alternate functions
+    table at <https://raw.githubusercontent.com/wipy/wipy/master/docs/PinOUT.png>`_
+    for the specific alternate functions that each pin supports.
 
-    # create an output pin on GPIO0
-    p0 = Pin(0, Pin.OUT)
-    p0.value(0)
-    p0.value(1)
+    For interrupts, the ``priority`` can take values in the range 1-7.  And the
+    ``wake`` parameter has the following properties:
 
-    # create an input pin on GPIO2
-    p2 = Pin(2, Pin.IN, Pin.PULL_UP)
-    print(p2.value())
+      - If ``wake_from=machine.Sleep.ACTIVE`` any pin can wake the board.
+      - If ``wake_from=machine.Sleep.SUSPENDED`` pins ``GP2``, ``GP4``, ``GP10``,
+        ``GP11``, GP17`` or ``GP24`` can wake the board. Note that only 1
+        of this pins can be enabled as a wake source at the same time, so, only
+        the last enabled pin as a ``machine.Sleep.SUSPENDED`` wake source will have effect.
+      - If ``wake_from=machine.Sleep.SUSPENDED`` pins ``GP2``, ``GP4``, ``GP10``,
+        ``GP11``, ``GP17`` and ``GP24`` can wake the board. In this case all of the
+        6 pins can be enabled as a ``machine.Sleep.HIBERNATE`` wake source at the same time.
 
 Constructors
 ------------
 
-.. class:: Pin(id, ...)
+.. class:: Pin(id, mode=-1, pull=-1, \*, value, drive, alt)
 
-   Create a new Pin object associated with the id.  If additional arguments are given,
-   they are used to initialise the pin.  See :meth:`Pin.init`.
+   Access the pin peripheral (GPIO pin) associated with the given ``id``.  If
+   additional arguments are given in the constructor then they are used to initialise
+   the pin.  Any settings that are not specified will remain in their previous state.
 
-Methods
--------
+   The arguments are:
 
-.. only:: port_wipy
+     - ``id`` is mandatory and can be an arbitrary object.  Among possible value
+       types are: int (an internal Pin identifier), str (a Pin name), and tuple
+       (pair of [port, pin]).
 
-    .. method:: Pin.init(mode, pull, \*, drive, alt)
-    
-       Initialise the pin:
+     - ``mode`` specifies the pin mode, which can be one of:
 
-         - ``mode`` can be one of:
+       - ``Pin.IN`` - Pin is configured for input.  If viewed as an output the pin
+         is in high-impedance state.
 
-            - ``Pin.IN``  - input pin.
-            - ``Pin.OUT`` - output pin in push-pull mode.
-            - ``Pin.OPEN_DRAIN`` - output pin in open-drain mode.
-            - ``Pin.ALT`` - pin mapped to an alternate function.
-            - ``Pin.ALT_OPEN_DRAIN`` - pin mapped to an alternate function in open-drain mode.
+       - ``Pin.OUT`` - Pin is configured for (normal) output.
 
-         - ``pull`` can be one of:
+       - ``Pin.OPEN_DRAIN`` - Pin is configured for open-drain output. Open-drain
+         output works in the following way: if the output value is set to 0 the pin
+         is active at a low level; if the output value is 1 the pin is in a high-impedance
+         state.  Not all ports implement this mode, or some might only on certain pins.
 
-            - ``None`` - no pull up or down resistor.
-            - ``Pin.PULL_UP`` - pull up resistor enabled.
-            - ``Pin.PULL_DOWN`` - pull down resistor enabled.
+       - ``Pin.ALT`` - Pin is configured to perform an alternative function, which is
+         port specific.  For a pin configured in such a way any other Pin methods
+         (except :meth:`Pin.init`) are not applicable (calling them will lead to undefined,
+         or a hardware-specific, result).  Not all ports implement this mode.
 
-         - ``drive`` can be one of:
+       - ``Pin.ALT_OPEN_DRAIN`` - The Same as ``Pin.ALT``, but the pin is configured as
+         open-drain.  Not all ports implement this mode.
 
-            - ``Pin.LOW_POWER`` - 2mA drive capability.
-            - ``Pin.MED_POWER`` - 4mA drive capability.
-            - ``Pin.HIGH_POWER`` - 6mA drive capability.
+     - ``pull`` specifies if the pin has a (weak) pull resistor attached, and can be
+       one of:
 
-         - ``alt`` is the number of the alternate function. Please refer to the
-           `pinout and alternate functions table. <https://raw.githubusercontent.com/wipy/wipy/master/docs/PinOUT.png>`_
-           for the specific alternate functions that each pin supports.
+       - ``None`` - No pull up or down resistor.
+       - ``Pin.PULL_UP`` - Pull up resistor enabled.
+       - ``Pin.PULL_DOWN`` - Pull down resistor enabled.
 
-       Returns: ``None``.
+     - ``value`` is valid only for Pin.OUT and Pin.OPEN_DRAIN modes and specifies initial
+       output pin value if given, otherwise the state of the pin peripheral remains
+       unchanged.
 
-    .. method:: Pin.id()
+     - ``drive`` specifies the output power of the pin and can be one of: ``Pin.LOW_POWER``,
+       ``Pin.MED_POWER`` or ``Pin.HIGH_POWER``.  The actual current driving capabilities
+       are port dependent.  Not all ports implement this argument.
 
-       Get the pin id.
+     - ``alt`` specifies an alternate function for the pin and the values it can take are
+       port dependent.  This argument is valid only for ``Pin.ALT`` and ``Pin.ALT_OPEN_DRAIN``
+       modes.  It may be used when a pin supports more than one alternate function.  If only
+       one pin alternate function is supported the this argument is not required.  Not all
+       ports implement this argument.
 
-.. only:: port_esp8266
+   As specified above, the Pin class allows to set an alternate function for a particular
+   pin, but it does not specify any further operations on such a pin.  Pins configured in
+   alternate-function mode are usually not used as GPIO but are instead driven by other
+   hardware peripherals.  The only operation supported on such a pin is re-initialising,
+   by calling the constructor or :meth:`Pin.init` method.  If a pin that is configured in
+   alternate-function mode is re-initialised with ``Pin.IN``, ``Pin.OUT``, or
+   ``Pin.OPEN_DRAIN``, the alternate function will be removed from the pin.
 
-    .. method:: Pin.init(mode, pull=None, \*, value)
+Methods
+-------
 
-       Initialise the pin:
+.. method:: Pin.init(mode=-1, pull=-1, \*, value, drive, alt)
 
-         - `mode` can be one of:
+   Re-initialise the pin using the given parameters.  Only those arguments that
+   are specified will be set.  The rest of the pin peripheral state will remain
+   unchanged.  See the constructor documentation for details of the arguments.
 
-            - ``Pin.IN``  - input pin.
-            - ``Pin.OUT`` - output pin in push-pull mode.
+   Returns ``None``.
 
-         - `pull` can be one of:
+.. method:: Pin.value([x])
 
-            - ``None`` - no pull up or down resistor.
-            - ``Pin.PULL_UP`` - pull up resistor enabled.
+   This method allows to set and get the value of the pin, depending on whether
+   the argument ``x`` is supplied or not.
 
-         - if `value` is given then it is the output value to set the pin
-           if it is in output mode.
+   If the argument is omitted then this method gets the digital logic level of
+   the pin, returning 0 or 1 corresponding to low and high voltage signals
+   respectively.  The behaviour of this method depends on the mode of the pin:
 
-.. method:: Pin.value([value])
+     - ``Pin.IN`` - The method returns the actual input value currently present
+       on the pin.
+     - ``Pin.OUT`` - The behaviour and return value of the method is undefined.
+     - ``Pin.OPEN_DRAIN`` - If the pin is in state '0' then the behaviour and
+       return value of the method is undefined.  Otherwise, if the pin is in
+       state '1', the method returns the actual input value currently present
+       on the pin.
 
-   Get or set the digital logic level of the pin:
+   If the argument is supplied then this method sets the digital logic level of
+   the pin.  The argument ``x`` can be anything that converts to a boolean.
+   If it converts to ``True``, the pin is set to state '1', otherwise it is set
+   to state '0'.  The behaviour of this method depends on the mode of the pin:
 
-     - With no argument, return 0 or 1 depending on the logic level of the pin.
-     - With ``value`` given, set the logic level of the pin.  ``value`` can be
-       anything that converts to a boolean.  If it converts to ``True``, the pin
-       is set high, otherwise it is set low.
+     - ``Pin.IN`` - The value is stored in the output buffer for the pin.  The
+       pin state does not change, it remains in the high-impedance state.  The
+       stored value will become active on the pin as soon as it is changed to
+       ``Pin.OUT`` or ``Pin.OPEN_DRAIN`` mode.
+     - ``Pin.OUT`` - The output buffer is set to the given value immediately.
+     - ``Pin.OPEN_DRAIN`` - If the value is '0' the pin is set to a low voltage
+       state.  Otherwise the pin is set to high-impedance state.
 
-.. method:: Pin.__call__([value])
+   When setting the value this method returns ``None``.
 
-   Pin objects are callable. The call method provides a (fast) shortcut to set and get the value of the pin.
-   See :func:`Pin.value` for more details.
+.. method:: Pin.out_value()
 
-.. method:: Pin.alt_list()
+   Return the value stored in the output buffer of a pin, regardless of its mode.
 
-    Returns a list of the alternate functions supported by the pin. List items are
-    a tuple of the form: ``('ALT_FUN_NAME', ALT_FUN_INDEX)``
+   Not all ports implement this method.
 
-    Availability: WiPy.
+.. method:: Pin.__call__([x])
 
-.. only:: port_wipy
+   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.toggle()
+
+   Toggle the output value of the pin.  Equivalent to ``pin.value(not pin.out_value())``.
+   Returns ``None``.
+
+   Not all ports implement this method.
 
-    .. method:: Pin.toggle()
+   Availability: WiPy.
 
-        Toggle the value of the pin.
+.. method:: Pin.id()
 
-    .. method:: Pin.mode([mode])
+   Get the pin identifier.  This may return the ``id`` as specified in the
+   constructor.  Or it may return a canonical software-specific pin id.
 
-        Get or set the pin mode.
+.. method:: Pin.mode([mode])
 
-    .. method:: Pin.pull([pull])
+   Get or set the pin mode.
+   See the constructor documentation for details of the ``mode`` argument.
 
-        Get or set the pin pull.
+.. method:: Pin.pull([pull])
 
-    .. method:: Pin.drive([drive])
+   Get or set the pin pull state.
+   See the constructor documentation for details of the ``pull`` argument.
 
-        Get or set the pin drive strength.
+.. method:: Pin.drive([drive])
 
-    .. method:: Pin.irq(\*, trigger, priority=1, handler=None, wake=None)
+   Get or set the pin drive strength.
+   See the constructor documentation for details of the ``drive`` argument.
 
-        Create a callback to be triggered when the input level at the pin changes.
+   Not all ports implement this method.
 
-            - ``trigger`` configures the pin level which can generate an interrupt. Possible values are:
+   Availability: WiPy.
 
-                - ``Pin.IRQ_FALLING`` interrupt on falling edge.
-                - ``Pin.IRQ_RISING`` interrupt on rising edge.
-                - ``Pin.IRQ_LOW_LEVEL`` interrupt on low level.
-                - ``Pin.IRQ_HIGH_LEVEL`` interrupt on high level.
-              
-              The values can be *ORed* together, for instance mode=Pin.IRQ_FALLING | Pin.IRQ_RISING
+.. method:: Pin.irq(handler=None, trigger=(Pin.IRQ_FALLING | Pin.IRQ_RISING), \*, priority=1, wake=None)
 
-            - ``priority`` level of the interrupt. Can take values in the range 1-7.
-              Higher values represent higher priorities.
-            - ``handler`` is an optional function to be called when new characters arrive.
-            - ``wakes`` selects the power mode in which this interrupt can wake up the
-              board. Please note:
+   Configure an interrupt handler to be called when the trigger source of the
+   pin is active.  If the pin mode is ``Pin.IN`` then the trigger source is
+   the external value on the pin.  If the pin mode is ``Pin.OUT`` then the
+   trigger source is the output buffer of the pin.  Otherwise, if the pin mode
+   is ``Pin.OPEN_DRAIN`` then the trigger source is the output buffer for
+   state '0' and the external pin value for state '1'.
 
-              - If ``wake_from=machine.Sleep.ACTIVE`` any pin can wake the board.
-              - If ``wake_from=machine.Sleep.SUSPENDED`` pins ``GP2``, ``GP4``, ``GP10``,
-                ``GP11``, GP17`` or ``GP24`` can wake the board. Note that only 1
-                of this pins can be enabled as a wake source at the same time, so, only
-                the last enabled pin as a ``machine.Sleep.SUSPENDED`` wake source will have effect.
-              - If ``wake_from=machine.Sleep.SUSPENDED`` pins ``GP2``, ``GP4``, ``GP10``,
-                ``GP11``, ``GP17`` and ``GP24`` can wake the board. In this case all of the
-                6 pins can be enabled as a ``machine.Sleep.HIBERNATE`` wake source at the same time.
-              - Values can be ORed to make a pin generate interrupts in more than one power
-                mode.
+   The arguments are:
 
-            Returns a callback object.
+     - ``handler`` is an optional function to be called when the interrupt
+       triggers.
 
-.. only:: port_esp8266
+     - ``trigger`` configures the event which can generate an interrupt.
+       Possible values are:
 
-    .. method:: Pin.irq(\*, trigger, handler=None)
+       - ``Pin.IRQ_FALLING`` interrupt on falling edge.
+       - ``Pin.IRQ_RISING`` interrupt on rising edge.
+       - ``Pin.IRQ_LOW_LEVEL`` interrupt on low level.
+       - ``Pin.IRQ_HIGH_LEVEL`` interrupt on high level.
 
-        Create a callback to be triggered when the input level at the pin changes.
+       These values can be OR'ed together to trigger on multiple events.
 
-            - ``trigger`` configures the pin level which can generate an interrupt. Possible values are:
+     - ``priority`` sets the priority level of the interrupt.  The values it
+       can take are port-specific, but higher values always represent higher
+       priorities.
+
+     - ``wake`` selects the power mode in which this interrupt can wake up the
+       system.  It can be ``machine.IDLE``, ``machine.SLEEP`` or ``machine.DEEPSLEEP``.
+       These values can also be OR'ed together to make a pin generate interrupts in
+       more than one power mode.
+
+   This method returns a callback object.
+
+.. only:: port_wipy
 
-                - ``Pin.IRQ_FALLING`` interrupt on falling edge.
-                - ``Pin.IRQ_RISING`` interrupt on rising edge.
+    .. method:: Pin.alt_list()
 
-              The values can be OR'ed together to trigger on multiple events.
+       Returns a list of the alternate functions supported by the pin. List items are
+       a tuple of the form: ``('ALT_FUN_NAME', ALT_FUN_INDEX)``
 
-            - ``handler`` is an optional function to be called when the interrupt triggers.
+       Availability: WiPy.
 
-            Returns a callback object.
 
 Attributes
 ----------
@@ -239,7 +317,8 @@ not all constants are available on all ports.
 .. data:: Pin.PULL_UP
           Pin.PULL_DOWN
 
-   Selects the whether there is a pull up/down resistor.
+   Selects whether there is a pull up/down resistor.  Use the value
+   ``None`` for no pull.
 
 .. data:: Pin.LOW_POWER
           Pin.MED_POWER
diff --git a/docs/library/machine.SPI.rst b/docs/library/machine.SPI.rst
index 73b3a3996..dda6314fa 100644
--- a/docs/library/machine.SPI.rst
+++ b/docs/library/machine.SPI.rst
@@ -1,10 +1,14 @@
 .. currentmodule:: machine
 
-class SPI -- a master-driven serial protocol
-============================================
+class SPI -- a Serial Peripheral Interface bus protocol (master side)
+=====================================================================
 
-SPI is a serial protocol that is driven by a master.  At the physical level
-there are 3 lines: SCK, MOSI, MISO.
+SPI is a synchronous serial protocol that is driven by a master. At the
+physical level, a bus consists of 3 lines: SCK, MOSI, MISO. Multiple devices
+can share the same bus. Each device should have a separate, 4th signal,
+SS (Slave Select), to select a particualr device on a bus with which
+communication takes place. Management of an SS signal should happen in
+user code (via machine.Pin class).
 
 .. only:: port_wipy
 
@@ -21,65 +25,84 @@ there are 3 lines: SCK, MOSI, MISO.
 Constructors
 ------------
 
-.. only:: port_wipy
+.. class:: SPI(id, ...)
 
-    .. class:: SPI(id, ...)
+   Construct an SPI object on the given bus, ``id``. Values of ``id`` depend
+   on a particular port and its hardware. Values 0, 1, etc. are commonly used
+   to select hardware SPI block #0, #1, etc. Value -1 can be used for
+   bitbanging (software) implementation of SPI (if supported by a port).
 
-       Construct an SPI object on the given bus.  ``id`` can be only 0.
-       With no additional parameters, the SPI object is created but not
-       initialised (it has the settings from the last initialisation of
-       the bus, if any).  If extra arguments are given, the bus is initialised.
-       See ``init`` for parameters of initialisation.
+   With no additional parameters, the SPI object is created but not
+   initialised (it has the settings from the last initialisation of
+   the bus, if any).  If extra arguments are given, the bus is initialised.
+   See ``init`` for parameters of initialisation.
 
 Methods
 -------
 
-.. method:: SPI.init(mode, baudrate=1000000, \*, polarity=0, phase=0, bits=8, firstbit=SPI.MSB, pins=(CLK, MOSI, MISO))
+.. method:: SPI.init(baudrate=1000000, \*, polarity=0, phase=0, bits=8, firstbit=SPI.MSB, sck=None, mosi=None, miso=None, pins=(SCK, MOSI, MISO))
 
    Initialise the SPI bus with the given parameters:
 
-     - ``mode`` must be ``SPI.MASTER``.
      - ``baudrate`` is the SCK clock rate.
      - ``polarity`` can be 0 or 1, and is the level the idle clock line sits at.
      - ``phase`` can be 0 or 1 to sample data on the first or second clock edge
        respectively.
-     - ``bits`` is the width of each transfer, accepted values are 8, 16 and 32.
-     - ``firstbit`` can be ``SPI.MSB`` only.
-     - ``pins`` is an optional tuple with the pins to assign to the SPI bus.
+     - ``bits`` is the width in bits of each transfer. Only 8 is guaranteed to be supported by all hardware.
+     - ``firstbit`` can be ``SPI.MSB`` or ``SPI.LSB``.
+     - ``sck``, ``mosi``, ``miso`` are pins (machine.Pin) objects to use for bus signals. For most
+       hardware SPI blocks (as selected by ``id`` parameter to the constructore), pins are fixed
+       and cannot be changed. In some cases, hardware blocks allow 2-3 alternative pin sets for
+       a hardware SPI block. Arbitrary pin assignments are possible only for a bitbanging SPI driver
+       (``id`` = -1).
+     - ``pins`` - WiPy port doesn't ``sck``, ``mosi``, ``miso`` arguments, and instead allows to
+     specify them as a tuple of ``pins`` paramter.
 
 .. method:: SPI.deinit()
 
    Turn off the SPI bus.
 
-.. method:: SPI.write(buf)
+.. method:: SPI.read(nbytes, write=0x00)
+
+    Read a number of bytes specified by ``nbytes`` while continuously writing
+    the single byte given by ``write``.
+    Returns a ``bytes`` object with the data that was read.
+
+.. method:: SPI.readinto(buf, write=0x00)
 
-    Write the data contained in ``buf``. 
-    Returns the number of bytes written.
+    Read into the buffer specified by ``buf`` while continuously writing the
+    single byte given by ``write``.
+    Returns ``None``.
 
-.. method:: SPI.read(nbytes, *, write=0x00)
+    Note: on WiPy this function returns the number of bytes read.
 
-    Read the ``nbytes`` while writing the data specified by ``write``.
-    Return the number of bytes read.
+.. method:: SPI.write(buf)
 
-.. method:: SPI.readinto(buf, *, write=0x00)
+    Write the bytes contained in ``buf``.
+    Returns ``None``.
 
-    Read into the buffer specified by ``buf`` while writing the data specified by
-    ``write``.
-    Return the number of bytes read.
+    Note: on WiPy this function returns the number of bytes written.
 
 .. method:: SPI.write_readinto(write_buf, read_buf)
 
-    Write from ``write_buf`` and read into ``read_buf``. Both buffers must have the
+    Write the bytes from ``write_buf`` while reading into ``read_buf``.  The
+    buffers can be the same or different, but both buffers must have the
     same length.
-    Returns the number of bytes written
+    Returns ``None``.
+
+    Note: on WiPy this function returns the number of bytes written.
 
 Constants
 ---------
 
 .. data:: SPI.MASTER
 
-   for initialising the SPI bus to master
+   for initialising the SPI bus to master; this is only used for the WiPy
 
 .. data:: SPI.MSB
 
    set the first bit to be the most significant bit
+
+.. data:: SPI.LSB
+
+   set the first bit to be the least significant bit
diff --git a/docs/library/network.rst b/docs/library/network.rst
index 0e18106aa..251e68c76 100644
--- a/docs/library/network.rst
+++ b/docs/library/network.rst
@@ -5,11 +5,12 @@
 .. module:: network
    :synopsis: network configuration
 
-This module provides network drivers and routing configuration.  Network
-drivers for specific hardware are available within this module and are
-used to configure a hardware network interface.  Configured interfaces
-are then available for use via the :mod:`socket` module. To use this module
-the network build of firmware must be installed.
+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`
+module.
 
 For example::
 
@@ -79,7 +80,7 @@ For example::
     class CC3K
     ==========
     
-    This class provides a driver for CC3000 wifi modules.  Example usage::
+    This class provides a driver for CC3000 WiFi modules.  Example usage::
     
         import network
         nic = network.CC3K(pyb.SPI(2), pyb.Pin.board.Y5, pyb.Pin.board.Y4, pyb.Pin.board.Y3)
@@ -128,16 +129,16 @@ For example::
     
     .. method:: cc3k.connect(ssid, key=None, \*, security=WPA2, bssid=None)
     
-       Connect to a wifi access point using the given SSID, and other security
+       Connect to a WiFi access point using the given SSID, and other security
        parameters.
     
     .. method:: cc3k.disconnect()
     
-       Disconnect from the wifi access point.
+       Disconnect from the WiFi access point.
     
     .. method:: cc3k.isconnected()
     
-       Returns True if connected to a wifi access point and has a valid IP address,
+       Returns True if connected to a WiFi access point and has a valid IP address,
        False otherwise.
     
     .. method:: cc3k.ifconfig()
@@ -323,7 +324,7 @@ For example::
 
     .. method:: wlan.isconnected()
 
-        In case of STA mode, returns ``True`` if connected to a wifi access
+        In case of STA mode, returns ``True`` if connected to a WiFi access
         point and has a valid IP address.  In AP mode returns ``True`` when a
         station is connected. Returns ``False`` otherwise.
 
@@ -348,7 +349,7 @@ For example::
 
         # Set WiFi access point name (formally known as ESSID) and WiFi channel
         ap.config(essid='My AP', channel=11)
-        # Queey params one by one
+        # Query params one by one
         print(ap.config('essid'))
         print(ap.config('channel'))
 
@@ -433,7 +434,7 @@ For example::
 
     .. method:: wlan.connect(ssid, \*, auth=None, bssid=None, timeout=None)
 
-       Connect to a wifi access point using the given SSID, and other security
+       Connect to a WiFi access point using the given SSID, and other security
        parameters.
 
           - ``auth`` is a tuple with (sec, key). Security can be ``None``, ``WLAN.WEP``,
@@ -451,16 +452,16 @@ For example::
 
     .. method:: wlan.disconnect()
 
-       Disconnect from the wifi access point.
+       Disconnect from the WiFi access point.
 
     .. method:: wlan.isconnected()
 
-       In case of STA mode, returns ``True`` if connected to a wifi access point and has a valid IP address.
+       In case of STA mode, returns ``True`` if connected to a WiFi access point and has a valid IP address.
        In AP mode returns ``True`` when a station is connected, ``False`` otherwise.
 
     .. method:: wlan.ifconfig(if_id=0, config=['dhcp' or configtuple])
 
-       With no parameters given eturns a 4-tuple of ``(ip, subnet_mask, gateway, DNS_server)``.
+       With no parameters given returns a 4-tuple of ``(ip, subnet_mask, gateway, DNS_server)``.
 
        if ``'dhcp'`` is passed as a parameter then the DHCP client is enabled and the IP params
        are negotiated with the AP.
@@ -498,10 +499,10 @@ For example::
         Create a callback to be triggered when a WLAN event occurs during ``machine.SLEEP``
         mode. Events are triggered by socket activity or by WLAN connection/disconnection.
 
-            - ``handler`` is the function that gets called when the irq is triggered.
+            - ``handler`` is the function that gets called when the IRQ is triggered.
             - ``wake`` must be ``machine.SLEEP``.
 
-        Returns an irq object.
+        Returns an IRQ object.
 
     Constants
     ---------
diff --git a/docs/library/utime.rst b/docs/library/utime.rst
index 831067383..109c3560c 100644
--- a/docs/library/utime.rst
+++ b/docs/library/utime.rst
@@ -82,37 +82,128 @@ Functions
 
     .. function::  ticks_ms()
 
-        Returns an increasing millisecond counter with arbitrary reference point, 
-        that wraps after some (unspecified) value. The value should be treated as 
-        opaque, suitable for use only with ticks_diff().
+        Returns an increasing millisecond counter with an arbitrary reference point,
+        that wraps around after some value. This value is not explicitly exposed,
+        but we will refer to it as `TICKS_MAX` to simplify discussion. Period of
+        the values is `TICKS_PERIOD = TICKS_MAX + 1`. `TICKS_PERIOD` is guaranteed
+        to be a power of two, but otherwise may differ from port to port. The same
+        period value is used for all of ticks_ms(), ticks_us(), ticks_cpu() functions
+        (for simplicity). Thus, these functions will return a value in range
+        [0 .. `TICKS_MAX`], inclusive, total `TICKS_PERIOD` values. Note that only
+        non-negative values are used. For the most part, you should treat values
+        returned by these functions as opaque. The only operations available for them
+        are ``ticks_diff()`` and ``ticks_add()`` functions described below.
+
+        Note: Performing standard mathematical operations (+, -) or relational
+        operators (<, <=, >, >=) directly on these value will lead to invalid
+        result. Performing mathematical operations and then passing their results
+        as arguments to ``ticks_diff()`` or ``ticks_add()`` will also lead to
+        invalid results from the latter functions.
 
     .. function::  ticks_us()
 
        Just like ``ticks_ms`` above, but in microseconds.
 
-.. only:: port_wipy or port_pyboard
+.. function::  ticks_cpu()
+
+   Similar to ``ticks_ms`` and ``ticks_us``, but with the highest possible resolution
+   in the system. This is usually CPU clocks, and that's why the function is named that
+   way. But it doesn't have to a CPU clock, some other timing source available in a
+   system (e.g. high-resolution timer) can be used instead. The exact timing unit
+   (resolution) of this function is not specified on ``utime`` module level, but
+   documentation for a specific port may provide more specific information. This
+   function is intended for very fine benchmarking or very tight real-time loops.
+   Avoid using it in portable code.
+
+   Availability: Not every port implements this function.
+
+
+.. function::  ticks_add(ticks, delta)
+
+   Offset ticks value by a given number, which can be either positive or negative.
+   Given a ``ticks`` value, this function allows to calculate ticks value ``delta``
+   ticks before or after it, following modular-arithmetic definition of tick values
+   (see ``ticks_ms()`` above). ``ticks`` parameter must be a direct result of call
+   to ``tick_ms()``, ``ticks_us()``, ``ticks_cpu()`` functions (or from previous
+   call to ``ticks_add()``). However, ``delta`` can be an arbitrary integer number
+   or numeric expression. ``ticks_add()`` is useful for calculating deadlines for
+   events/tasks. (Note: you must use ``ticks_diff()`` function to work with
+   deadlines.)
+
+   Examples::
+
+        # Find out what ticks value there was 100ms ago
+        print(tick_add(time.ticks_ms(), -100))
+
+        # Calculate deadline for operation and test for it
+        deadline = tick_add(time.ticks_ms(), 200)
+        while ticks_diff(deadline, time.ticks_ms()) > 0:
+            do_a_little_of_something()
+
+        # Find out TICKS_MAX used by this port
+        print(tick_add(0, -1))
+
+
+.. function::  ticks_diff(ticks1, ticks2)
+
+   Measure ticks difference between values returned from ticks_ms(), ticks_us(), or ticks_cpu()
+   functions. The argument order is the same as for subtraction operator,
+   ``tick_diff(ticks1, ticks2)`` has the same meaning as ``ticks1 - ticks2``. However, values returned by
+   ticks_ms(), etc. functions may wrap around, so directly using subtraction on them will
+   produce incorrect result. That is why ticks_diff() is needed, it implements modular
+   (or more specifically, ring) arithmetics to produce correct result even for wrap-around
+   values (as long as they not 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` 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 2 tick values are apart for `TICKS_PERIOD/2-1`
+   ticks, that value will be returned by the function. However, if `TICKS_PERIOD/2` of
+   real-time ticks has passed between them, the function will return `-TICKS_PERIOD/2`
+   instead, i.e. result value will wrap around to the negative range of possible values.
+
+   Informal rationale of the constraints above: Suppose you are locked in a room with no
+   means to monitor passing of time except a standard 12-notch clock. Then if you look at
+   dial-plate now, and don't look again for another 13 hours (e.g., if you fall for a
+   long sleep), then once you finally look again, it may seem to you that only 1 hour
+   has passed. To avoid this mistake, just look at the clock regularly. Your application
+   should do the same. "Too long sleep" metaphor also maps directly to application
+   behavior: don't let your application run any single task for too long. Run tasks
+   in steps, and do time-keeping inbetween.
+
+   ``ticks_diff()`` is designed to accommodate various usage patterns, among them:
+
+   Polling with timeout. In this case, the order of events is known, and you will deal
+   only with positive results of ``ticks_diff()``::
+
+        # Wait for GPIO pin to be asserted, but at most 500us
+        start = time.ticks_us()
+        while pin.value() == 0:
+            if time.ticks_diff(time.ticks_us(), start) > 500:
+                raise TimeoutError
+
+   Scheduling events. In this case, ``ticks_diff()`` result may be negative
+   if an event is overdue::
+
+        # This code snippet is not optimized
+        now = time.ticks_ms()
+        scheduled_time = task.scheduled_time()
+        if ticks_diff(now, scheduled_time) > 0:
+            print("Too early, let's nap")
+            sleep_ms(ticks_diff(now, scheduled_time))
+            task.run()
+        elif ticks_diff(now, scheduled_time) == 0:
+            print("Right at time!")
+            task.run()
+        elif ticks_diff(now, scheduled_time) < 0:
+            print("Oops, running late, tell task to run faster!")
+            task.run(run_faster=true)
+
+   Note: Do not pass ``time()`` values to ``ticks_diff()``, and should use
+   normal mathematical operations on them. But note that ``time()`` may (and will)
+   also overflow. This is known as https://en.wikipedia.org/wiki/Year_2038_problem .
 
-    .. function::  ticks_cpu()
-
-       Similar to ``ticks_ms`` and ``ticks_us``, but with higher resolution (usually CPU clocks).
-
-.. only:: port_unix or port_pyboard or port_wipy or port_esp8266
-
-    .. function::  ticks_diff(old, new)
-
-       Measure period between consecutive calls to ticks_ms(), ticks_us(), or ticks_cpu(). 
-       The value returned by these functions may wrap around at any time, so directly 
-       subtracting them is not supported. ticks_diff() should be used instead. "old" value should 
-       actually precede "new" value in time, or result is undefined. This function should not be
-       used to measure arbitrarily long periods of time (because ticks_*() functions wrap around 
-       and usually would have short period). The expected usage pattern is implementing event 
-       polling with timeout::
-
-            # Wait for GPIO pin to be asserted, but at most 500us
-            start = time.ticks_us()
-            while pin.value() == 0:
-                if time.ticks_diff(start, time.ticks_us()) > 500:
-                    raise TimeoutError
 
 .. function:: time()