Split I2C support into master part - I2C class, and slave - I2CSlave, ditto for SPI. Master API is well-specified. Slave is largely TBD,

Hardware-API.md

@@ -171,13 +171,15 @@ Methods:
 - `uart.write(buf)` NOHEAP
 - `uart.sendbreak()` NOHEAP
 
-## The I2C class
+## The I2C class - I2C Master end-point
 
-`i2c = I2C(id, mode, *, baudrate, addr, pins)`
+Changes from pyb: re-cast for master-only support (slave moved to I2CSlave class), so "mode" arg removed, changed method names.
 
-`pins` is a tuple/list of SDA,SCL pins in that order (or should it be SCL, SDA to be consistent with the clock first for SPI?).
+`i2c = I2C(id, *, baudrate, addr, pins)`
 
-Master mode:
+`pins` is a tuple/list of SDA,SCL pins in that order (TODO: or should it be SCL, SDA to be consistent with the clock first for SPI?).
+
+This class implements only master mode operations:
 
 - `i2c.scan()` search for devices present on the bus.
 
@@ -195,15 +197,24 @@ Master mode mem transfers:
 
 For master transfers we don't use read/write names because the type signature here is different to standard read/write (here we need to specify the address of the target slave).  Other option would be to provide `i2c.set_addr(addr)` to set the slave address and then we can simply use standard read/readinto/write methods.  But that introduces state into the I2C master (being the slave address) and really turns it into an endpoint, which is a higher level concept than simply providing basic methods to read/write on the I2C bus.  An endpoint wrapper can very easily be written in Python.
 
+## The I2CSlave class - I2C Slave end-point
+
+`i2csl = I2CSlave(id, *, baudrate, addr, pins)`
+
+See I2C class for arguments (id's refer to the same underlying hardware blocks as master I2C class).
+
 Slave mode:
 
+TODO: Details TBD. The general idea is that slave end-point can be configured in such a way that it can be accessed by master I2C.readfrom_mem(), etc. methods. Actual ability to do that depends largely on underlying hardware, and would require low-latency interrupts and DMA support.
+
 - `i2c.read(nbytes)`
 - `i2c.readinto(buf)` NOHEAP
 - `i2c.write(buf)` NOHEAP
 
-## The SPI class
+## The SPI class - SPI master end-point
+Changes from pyb: re-cast for master-only support (slave moved to SPISlave class), so "mode" arg removed, changed method names.
 
-`spi = SPI(id, mode, *, baudrate, polarity=1, phase=0, bits=8, firstbit=SPI.MSB, pins)`
+`spi = SPI(id, *, baudrate, polarity=1, phase=0, bits=8, firstbit=SPI.MSB, pins)`
 
 `pins` is a tuple/list of SCK,MOSI,MISO pins in that order.  Optionally the list can also have NSS at the end.
 
@@ -214,6 +225,10 @@ Methods:
 - `spi.readinto(buf, *, write=0x00)` NOHEAP
 - `spi.write_readinto(write_buf, read_buf)` NOHEAP; write_buf and read_buf can be the same
 
+## The SPISlave class - SPI slave end-point
+
+TODO: Details TBD. As SPI usually offer (much) higher transfer speeds, implementing slave support would require even more performant resources that I2C slave. One of the usecases may be high-speed communication between 2 or more systems, akin to "remote DMA" (i.e. slave will be initialized with a single bytearary buffer, which master can read at any time).
+
 ## The I2S class
 
 **Note that I2S has not yet officially supported by any existing