docs/machine.I2C: Add writevto method to write a vector of byte bufs.

This allows to efficiently send to an I2C slave data that is made up of
more than one buffer.  Instead of needing to allocate temporary memory to
combine buffers together this new method allows to pass in a tuple or list
of buffers.  The name is based on the POSIX function writev() which has
similar intentions and signature.

The reasons for taking this approach (compared to having an interface with
separate start/write/stop methods) are:
- It's a backwards compatible extension.
- It's convenient for the user.
- It's efficient because there is only one Python call, then the C code can
  do everything in one go.
- It's efficient on the I2C bus because the implementation can do
  everything in one go without pauses between blocks of bytes.
- It should be possible to implement this extension in all ports, for
  hardware and software I2C.

Further discussion is found in issue #3482, PR #4020 and PR #4763.
This commit is contained in:
Damien George 2018-08-04 16:18:52 +10:00
parent 1f63e9b701
commit 8bec0e869d

View File

@ -131,6 +131,20 @@ operations that target a given slave device.
generated at the end of the transfer, even if a NACK is received.
The function returns the number of ACKs that were received.
.. method:: I2C.writevto(addr, vector, stop=True)
Write the bytes contained in *vector* to the slave specified by *addr*.
*vector* should be a tuple or list of objects with the buffer protocol.
The *addr* is sent once and then the bytes from each object in *vector*
are written out sequentially. The objects in *vector* may be zero bytes
in length in which case they don't contribute to the output.
If a NACK is received following the write of a byte from one of the
objects in *vector* then the remaining bytes, and any remaining objects,
are not sent. If *stop* is true then a STOP condition is generated at
the end of the transfer, even if a NACK is received. The function
returns the number of ACKs that were received.
Memory operations
-----------------