Merge remote-tracking branch 'micropython/master'

Conflicts:
	README.md - Kept Adafruit README.md intact.
	py/emitglue.c - Added xtensa architecture as an OR of the define.
	zephyr/README.md - Fixed spelling mistake.

1 files changed, 50 insertions, 29 deletions

diff --git a/docs/library/machine.SPI.rst b/docs/library/machine.SPI.rst
index 73b3a3996..9b4d62e01 100644
--- a/docs/library/machine.SPI.rst
+++ b/docs/library/machine.SPI.rst
@@ -1,10 +1,13 @@
 .. currentmodule:: machine
 
-class SPI -- a master-driven serial protocol
-============================================
+class SPI -- a Serial Peripheral Interface bus protocol
+=======================================================
 
-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 serial protocol that is driven by a master.  At the physical level,
+bus consistens 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 +24,83 @@ 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, pins=(CLK, MOSI, MISO), sck=None, mosi=None, miso=None)
 
    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 of is guaranteed to be supported by all hardware.
+     - ``firstbit`` can be ``SPI.MSB`` or ``SPI.LSB``.
+     - ``pins`` is an optional tuple with the pins to assign to the SPI bus (deprecated, only for WiPy).
+     - ``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).
 
 .. 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