From 8bec0e869d2285275487faebcc21a6278ebd311e Mon Sep 17 00:00:00 2001 From: Damien George Date: Sat, 4 Aug 2018 16:18:52 +1000 Subject: [PATCH] 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. --- docs/library/machine.I2C.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/library/machine.I2C.rst b/docs/library/machine.I2C.rst index 71ca9b0d3..f58912437 100644 --- a/docs/library/machine.I2C.rst +++ b/docs/library/machine.I2C.rst @@ -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 -----------------