docs/machine.SPI: Bring up to date with Hardware API, make vendor-neutral.

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
+SPI is a serial protocol that is driven by a master.  At the physical level,
-there are 3 lines: SCK, MOSI, MISO.
+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,11 +24,13 @@ 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.
@@ -34,18 +39,22 @@ Constructors
 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.
+     - ``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`` only.
+     - ``firstbit`` can be ``SPI.MSB`` or ``SPI.LSB``.
-     - ``pins`` is an optional tuple with the pins to assign to the SPI bus.
+     - ``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 alterbative pin sets for
+       a hardware SPI block. Arbitrary pin assignments are possible only for a bitbanging SPI driver
+       (``id``=-1).
 
 .. method:: SPI.deinit()
 
@@ -71,7 +80,7 @@ Methods
 
     Write from ``write_buf`` and read into ``read_buf``. Both buffers must have the
     same length.
-    Returns the number of bytes written
+    Returns the number of bytes written.
 
 Constants
 ---------
@@ -83,3 +92,7 @@ Constants
 .. 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