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:
parent
1f63e9b701
commit
8bec0e869d
@ -131,6 +131,20 @@ operations that target a given slave device.
|
|||||||
generated at the end of the transfer, even if a NACK is received.
|
generated at the end of the transfer, even if a NACK is received.
|
||||||
The function returns the number of ACKs that were 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
|
Memory operations
|
||||||
-----------------
|
-----------------
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user